# Catálogo de eventos Source: https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos Todos os eventos de webhook da Finvia nas quatro famílias (cobrança, assinatura, saque e conta), com destinos e formato de cada uma. Esta página lista todas as notificações que a Finvia envia ao seu sistema. Use-a para saber quais eventos tratar, em que destino cada um chega e como reconhecer o formato do corpo. O detalhe de cada família, com payloads completos, está no guia correspondente. > [!NOTE] > > **Para o negócio:** cada família tem destinos próprios. O `charge.updated` com o chargeback formalizado, por exemplo, chega só no `postbackUrl` da cobrança, e o aviso de aprovação de subconta chega só na URL de aviso de status da subconta. Defina com o time técnico quais destinos a operação precisa antes de ir para produção. ## Destinos de entrega | Destino | Onde é configurado | O que recebe | | - | - | - | | **Endpoints de webhook** | Painel: **Configurações** > **Webhooks**, com a conta selecionada. API: [`POST /v1/webhook-endpoints`](/referencia/webhooks/criar-endpoint) | Eventos de cobrança, assinatura e saque da conta. Pela API, dá para filtrar com `enabled_events`; pelo painel, o endpoint recebe todos | | **Endpoints da master com subcontas** | Os mesmos endpoints da conta master, com a opção de incluir subcontas (`include_submerchants: true`) | Também os eventos de cobrança, assinatura e saque das subcontas | | **`postbackUrl` da cobrança** | Campo `postbackUrl` em `POST /v1/charges` | Os mesmos eventos de cobrança dos endpoints, mais o `charge.updated` legado. Não há filtro de eventos | | **URL de aviso de status de conta** | Campo `postbackUrl` em `POST /v1/submerchants`, gravado como `merchant_status_postback_url` da subconta | Só o aviso de status da subconta | Os eventos são roteados pela conta dona do recurso. A regra completa está em [Quem recebe cada evento](/guias/webhooks/visao-geral#quem-recebe-cada-evento). ## Todos os eventos | Evento | Família | Quando é enviado | Endpoints | `postbackUrl` | | - | - | - | - | - | | `charge.created` | Cobrança | A cobrança é criada | Sim | Sim | | `charge.pending` | Cobrança | O processamento termina em `pending` (ex.: QR Code Pix gerado) | Sim | Sim | | `charge.paid` | Cobrança | O pagamento é confirmado, na hora ou depois | Sim | Sim | | `charge.refused` | Cobrança | A cobrança é recusada na criação ou ao final do 3DS gerenciado | Sim | Sim | | `charge.failed` | Cobrança | A cobrança falha na criação ou ao final do 3DS gerenciado | Sim | Sim | | `charge.refunded` | Cobrança | O estorno é concluído (inclusive no alerta de pré-chargeback com estorno e na reversão de saldo de um chargeback) | Sim | Sim | | `charge.pre_chargeback` | Cobrança | Um alerta de pré-chargeback é registrado | Sim | Sim | | `charge.blocked` | Cobrança | A cobrança é bloqueada (MED ou chargeback em análise) | Sim | Sim | | `charge.updated` | Cobrança (legado) | O adquirente informa mudança de status (pagamento, recusa ou falha assíncrona, estorno, chargeback), o 3DS gerenciado termina em recusa ou falha, a cobrança é bloqueada ou recebe alerta de pré-chargeback | **Não** | Sim | | `subscription.created` | Assinatura | Uma nova assinatura é criada | Sim | Não se aplica | | `subscription.activated` | Assinatura | A assinatura é ativada (primeira cobrança aprovada, início do trial ou aprovação da primeira cobrança que estava em análise) | Sim | Não se aplica | | `subscription.renewed` | Assinatura | Uma cobrança recorrente é aprovada (inclui a primeira cobrança cheia depois do trial) | Sim | Não se aplica | | `subscription.payment_failed` | Assinatura | Cada tentativa de cobrança da assinatura que falha | Sim | Não se aplica | | `subscription.cancelled` | Assinatura | A assinatura é cancelada | Sim | Não se aplica | | `subscription.expired` | Assinatura | A assinatura é encerrada (retentativas esgotadas ou `endDate` do plano) | Sim | Não se aplica | | `payout.approved` | Saque | O saque de uma subconta é aprovado e enviado para pagamento | Sim | Não se aplica | | `payout.rejected` | Saque | O saque de uma subconta é rejeitado | Sim | Não se aplica | | (sem nome de evento) | Conta | O status da subconta muda para `pre_approved`, `correcting`, `active` (aprovação ou desbloqueio), `rejected` ou `blocked` | Não | Não. Vai para a URL de aviso de status | > [!NOTE] > > `subscription.trial_started` e `subscription.trial_ended` existem no contrato de tipos, mas **não são entregues** hoje. Para acompanhar o trial, use `subscription.activated` e `subscription.renewed`, que trazem o objeto `trial`. Não há evento para a liberação de um bloqueio nem para a criação de um saque. > [!WARNING] > > Recusas e falhas informadas **depois** pelo adquirente (cobrança em análise negada, Pix cancelado ou expirado) geram só o `charge.updated` no `postbackUrl`. A cobrança recorrente de assinatura recusada gera `subscription.payment_failed` e não gera `charge.refused`. O chargeback formalizado chega como `charge.updated` com `status: "chargeback"` e, quando o valor sai do saldo, também como `charge.refunded`. O desenho abaixo mostra quais eventos saem da criação da cobrança até o primeiro resultado, e para qual destino vai cada um. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(234,243,255) Finvia participant F as Finvia end box rgb(243,245,248) Sua aplicação participant E as Endpoints de webhook participant P as postbackUrl da cobrança end box rgb(244,240,255) Fora da Finvia participant A as Adquirente ou Pix end Note over F,P: Cobrança gravada F-)E: charge.created F-)P: charge.created alt Termina em pending (Pix com QR Code) F-)E: charge.pending F-)P: charge.pending else Aprovada na hora F-)E: charge.paid F-)P: charge.paid else Recusada ou falhou (inclusive no fim do 3DS gerenciado) F-)E: charge.refused ou charge.failed F-)P: charge.refused ou charge.failed · no fim do 3DS gerenciado, também charge.updated else in_analysis ou authentication_required Note over F,P: Só o charge.created. O próximo evento depende do desfecho end opt Mudança informada depois pelo adquirente A->>F: pagamento, recusa, falha ou estorno F-)E: charge.paid ou charge.refunded, se for o caso F-)P: os mesmos eventos e também charge.updated Note over E,P: Recusa, falha, cancelamento ou expiração depois da criação: só charge.updated na postbackUrl end ``` O desenho abaixo mostra os eventos que podem chegar depois que a cobrança está paga. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart LR PAID(["Cobrança
paid"]):::ok M1["Estorno concluído"]:::neutro M2["Alerta de
pré-chargeback"]:::alerta M3["Bloqueio
MED ou disputa"]:::alerta M5["Chargeback
formalizado"]:::erro E1[["charge.refunded
endpoints e postbackUrl"]]:::evento E2[["charge.pre_chargeback
endpoints e postbackUrl"]]:::evento R2[["charge.refunded
se houve estorno"]]:::evento L2[["charge.updated
só na postbackUrl"]]:::evento E3[["charge.blocked
endpoints e postbackUrl"]]:::evento L3[["charge.updated
só na postbackUrl"]]:::evento E4["Nenhum evento
consulte a cobrança"]:::neutro E5[["charge.updated
status chargeback
só na postbackUrl"]]:::evento R5[["charge.refunded
se o valor sai do saldo"]]:::evento PAID --> M1 --> E1 PAID --> M2 M2 --> E2 M2 --> R2 M2 --> L2 PAID --> M3 M3 --> E3 M3 --> L3 M3 -.->|"bloqueio retirado"| E4 PAID --> M5 M5 --> E5 M5 --> R5 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` O desenho abaixo mostra a ordem dos eventos de assinatura, todos entregues aos endpoints de webhook. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB C(["POST /v1/subscriptions"]):::neutro E0[["subscription.created"]]:::evento Q{"Primeira
cobrança?"}:::decisao E1[["subscription.activated
aprovada ou trial iniciado"]]:::evento E2[["subscription.payment_failed
assinatura não ativa"]]:::evento E3[["subscription.renewed
a cada ciclo aprovado"]]:::evento E4[["subscription.payment_failed
a cada tentativa recusada"]]:::evento E5[["subscription.cancelled"]]:::evento E6[["subscription.expired
encerrada"]]:::evento C --> E0 --> Q Q -->|"aprovada, trial ou
análise aprova"| E1 Q -->|"recusada ou
análise nega"| E2 E1 --> E3 E1 --> E4 E4 -->|"retentativas acabam"| E6 E1 -->|"cancelamento"| E5 E3 -->|"plano chega
ao endDate"| E6 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ## Formato por família | Família | Envelope | Chaves | Exceções | | - | - | - | - | | Cobrança (envelope padrão) | `{ id, event, livemode, data }` | snake\_case no primeiro nível de `data` | Objetos aninhados em camelCase (`payment_method`, `shipping_address`, `tracking_info`, `three_ds`, `freight_details`, `payment_details`). `metadata` como foi enviada | | `charge.updated` | `{ event, data }`, sem `id` e sem `livemode` | camelCase em todos os níveis | `metadata` também em camelCase (veja [Metadata](/guias/cobrancas/visao-geral#metadata)) | | Assinatura | `{ id, event, livemode, data }` | snake\_case | `trial` em camelCase. `metadata` como foi enviada | | Saque | `{ id, event, data }`, sem `livemode` | camelCase | O `id` da raiz é o id do saque. Valores em texto decimal com 8 casas | | Aviso de status de conta | Sem envelope | camelCase | Sem nome de evento e sem id | A explicação completa, com exemplos, está em [Formato por família](/guias/webhooks/visao-geral#formato-por-família). ### Envelope padrão (cobrança e assinatura) ```json theme={null} { "id": "evt_1XcN7hJ4uQ2pZ8eL6wS3kF9a", "event": "charge.paid", "livemode": true, "data": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "paid", "amount": 100, "currency": "BRL", "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "paid_at": "2024-01-15T10:35:00.000Z", "is_test": false } } ``` | Campo | Descrição | | - | - | | `id` | Identificador do evento | | `event` | Nome do evento | | `livemode` | Nos eventos de cobrança, `false` indica cobrança de teste (`data.is_test: true`). Nas assinaturas, não use para separar teste de produção | | `data` | O objeto da cobrança ou da assinatura (o exemplo acima mostra só alguns campos) | ### Postback legado (`charge.updated`) Sem `id` e sem `livemode`. O `data` é a cobrança em camelCase, com `isBlocked`, `blockedAt` e `blockedReason` no bloqueio e, no pré-chargeback, `chargebackAlertRefunded` e `chargebackAlertReason`. ```json theme={null} { "event": "charge.updated", "data": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "chargeback", "amount": 100, "currency": "BRL", "merchantId": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia", "isTest": false } } ``` ### Envelope de saque Sem `livemode`. O `id` da raiz é o **id da solicitação de saque**. Campos em camelCase, valores em texto decimal. ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "event": "payout.rejected", "data": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "amount": "100.00000000", "currency": "BRL", "status": "rejected", "payoutFee": "1.00000000", "netAmount": "99.00000000", "rejectionReason": "Documentação incompleta" } } ``` ### Aviso de status de conta Sem envelope: o corpo é o próprio objeto da notificação, em camelCase. `rejectionReason` aparece só em `rejected` e `correcting`. `date` é a data de referência do status. ```json theme={null} { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "status": "correcting", "date": "2024-01-16T09:15:00.000Z", "rejectionReason": "Documento de identidade ilegível. Reenvie o RG ou CNH com qualidade adequada." } ``` ## Confirmação, entrega e deduplicação * **Confirmação de recebimento:** só uma resposta `2xx` em até 10 segundos conta como entregue. Redirecionamentos não são seguidos. * **Entrega e novas tentativas:** veja [Entrega e retentativas](/guias/webhooks/visao-geral#entrega-e-retentativas). * **Deduplicação:** o mesmo evento pode chegar mais de uma vez. A chave de cada formato está na [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos). * **Teste e produção:** a mesma lista de endpoints recebe os dois. Separe os eventos de cobrança por `livemode` e `is_test` (`isTest` no `charge.updated`). Saques e avisos de conta não têm marcação de teste. ## Segurança * Os webhooks não trazem assinatura HMAC: confirme o estado na API antes de uma ação crítica (veja [Regras de negócio dos webhooks](/guias/webhooks/visao-geral#regras-de-negócio)). * Use sempre HTTPS no endpoint. * Aplique limite de requisições no seu endpoint. * Responda rápido e processe depois: devolva `2xx` antes de executar lógica pesada. ## Como simular eventos No sandbox, [`POST /v1/charges/{id}/resend-webhook`](/referencia/cobrancas/reenviar-webhook-teste) gera um evento novo, com `id` novo, para uma cobrança de teste, com o status que você escolher (`paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis` ou `authentication_required`). O evento vai para o `postbackUrl` da cobrança e para os endpoints da própria conta. O payload simulado não é idêntico ao real, então não o use como referência de schema. ## Guias de cada família > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Payload completo de cada evento `charge.*` e do `charge.updated`. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos `subscription.*`, objeto `charge` e tipos de cancelamento. > [card] [Webhooks de saque](/guias/webhooks/saque) > > `payout.approved` e `payout.rejected` das subcontas. > [card] [Webhooks de conta](/guias/webhooks/conta) > > Avisos de aprovação, correção e bloqueio de subcontas. ## Veja também > [card] [Visão geral de webhooks](/guias/webhooks/visao-geral) > > Destinos, formatos, entrega e deduplicação. > [card] [Status de cobrança](/anexos/status-de-cobranca) > > O que cada status significa e o que fazer. # Catálogo de códigos de erro Source: https://docs.fastpaybrasil.com/anexos/codigos-de-erro As mensagens de erro da API da Finvia, agrupadas por rota, com a causa e a ação recomendada. Este catálogo reúne as respostas de erro de cada rota da API. As mensagens estão **exatamente** como a API as devolve: algumas em português, outras em inglês, às vezes na mesma rota. Use a página para montar o tratamento de erros, configurar alertas e orientar o suporte. Para o formato geral das respostas e a regra de quando repetir uma requisição, veja [Erros e como tratar](/primeiros-passos/erros). ## Como ler as tabelas | Coluna | Conteúdo | | - | - | | **HTTP** | Código de status da resposta | | **Mensagem ou código** | Valor literal de `message` ou, nas rotas que usam código de negócio, o valor de `code` (Apple Pay e validação de cartão) ou de `error` (envio de documentos com token). `X` e `Y` indicam valores que variam | | **Causa** | O que provoca o erro | | **Ação** | O que fazer | A API usa três formatos de corpo: | Formato | Onde | | - | - | | `{ "statusCode", "message", "error" }` | Padrão. Em erros de validação do corpo (`400`), `message` vem como lista, um item por problema | | `{ "code", "message" }` | Erros de negócio do Apple Pay e validação de cartão em `POST /v1/subscriptions` | | `{ "error", "message", "details" }` | Erros de arquivo em `POST /v1/document-uploads` | > [!TIP] > > **Para o desenvolvedor:** decida o fluxo pelo código HTTP e, quando existir, pelo `code` ou pelo `error` dos dois últimos formatos. Use o texto de `message` só para log e diagnóstico: ele mistura idiomas e pode mudar. ## Erros comuns a todas as rotas | HTTP | Mensagem | Causa | Ação | | - | - | - | - | | `400` | Lista em `message`, com `error` `Bad Request` (ex.: `["amount must not be less than 1"]`) | Campo obrigatório ausente, tipo errado ou valor fora do limite | Corrija cada item da lista e envie de novo | | `401` | `Unauthorized` | Chave inválida, cabeçalho `Authorization` ausente ou formato incorreto. O corpo é `{ "statusCode": 401, "message": "Unauthorized" }` | Confira a chave, o prefixo `Basic ` e se o Base64 decodificado termina em `:` | | `403` | `Acesso negado` | O perfil do usuário que gerou a chave não tem permissão para a rota. O corpo é `{ "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 }` | Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave) | | `500` | `Internal server error` | Erro interno | Em consultas, tente de novo com espera crescente. Em criações, verifique se o recurso foi criado antes de repetir | ## Cobranças ### `POST /v1/charges` | HTTP | Mensagem ou código | Causa | Ação | | - | - | - | - | | `400` | `Shipping info must be provided for merchants selling physical items.` | Algum item é `physical` e o corpo não traz `shippingAddress`. Nenhuma cobrança é criada | Envie `shippingAddress` com `postalCode`, `addressLine1`, `city`, `state` e `country` | | `400` | Lista em `message`, ex.: `["shippingAddress.country must be a valid ISO31661 Alpha3 code"]` | `shippingAddress` incompleto ou inválido, ou outro campo fora do contrato | Corrija os campos indicados. País em 3 letras (`BRA`) | | `400` | `CVV is required when using cardTokenId` | Cobrança com cartão salvo sem `cvv` | Colete o CVV do comprador e envie junto com o `cardTokenId` | | `400` | Erro de validação do cartão salvo | O cartão do `cardTokenId` está revogado, expirado ou pendente de ativação | Use outro cartão. Confira o status em `GET /v1/cards` | | `403` | `Acesso negado` | Chave de usuário Desenvolvedor | Gere a chave com usuário Owner ou Manager | | `422` | `Fees not configured` | A conta não tem taxa configurada para o método, a moeda ou o número de parcelas. Vale também no Modo Teste | Fale com o suporte da Finvia | | `500` | `Internal server error` | Erro interno | Siga o [procedimento de timeout](/primeiros-passos/paginacao-ordenacao-idempotencia#procedimento-depois-de-um-timeout-ao-criar-cobrança) antes de repetir | Recusas chegam com `201`, `status` `refused` ou `failed` e o motivo em `reason`. Também sai o webhook `charge.refused` ou `charge.failed`. | `reason` (literal) | Causa | Ação | | - | - | - | | `card_declined` | Recusa do cartão de teste `4444333322221112` no Modo Teste. Em produção, o `reason` traz o motivo informado pelo processador | Oferecer outro cartão ou Pix | | `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | A conta exige 3D Secure e a cobrança veio sem autenticação, ou o 3DS não pôde ser feito | Fazer a autenticação 3DS antes de criar a cobrança | | `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card` | O comprador não passou na autenticação | Pedir nova tentativa ou outro cartão | | `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` | 3DS obrigatório e `cryptogram` ou `eci` ausentes ou `null` | Repassar o resultado completo de `challenge-result`, sem enviar campos `null` | | `3ds_: Authentication did not succeed` | No 3DS gerenciado, a autenticação não passou (`` é o estado final) | Pedir nova tentativa ou outro cartão | | `antifraud_denied` | Recusa pela análise antifraude da conta | Oferecer outra forma de pagamento | Quando a análise antifraude manda a cobrança para revisão manual, ela fica `in_analysis` com `reason` `antifraud_manual_review`. Não é recusa: aguarde o desfecho. Erros de Apple Pay nesta rota, no formato `{ code, message }`: | HTTP | Código | Causa | Ação | | - | - | - | - | | `400` | `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` | `customer.document` ausente. O token da Apple não traz CPF ou CNPJ | Coletar o documento no checkout antes de abrir o Apple Pay | | `422` | `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | Moeda diferente de `BRL` | Usar `BRL` | | `400` | `APPLE_PAY_TOKEN_INVALID` | O objeto em `wallet.token` não está no formato do token da Apple | Enviar o `payment.token` na íntegra, sem reescrever campos | | `400` | `APPLE_PAY_PROVIDER_REJECTED` | O processador recusou a operação ou devolveu resposta fora do contrato | Verificar o token e tentar de novo. Persistindo, falar com o suporte | | `422` | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | O processador de Apple Pay não está configurado para a conta | Falar com o suporte | | `503` | `APPLE_PAY_PROVIDER_UNAVAILABLE` | Processador indisponível | Tentar de novo mais tarde | | `500` | `APPLE_PAY_PROVIDER_AUTH_FAILED` | Falha de autenticação entre a Finvia e o processador | Falar com o suporte | ### `GET /v1/charges` e `GET /v1/charges/{id}` | HTTP | Mensagem | Causa | Ação | | - | - | - | - | | `401` | `Unauthorized` | Credencial inválida | Ver erros comuns | | `403` | `Acesso negado` | Perfil sem permissão | Ver erros comuns | > [!WARNING] > > `GET /v1/charges/{id}` com um `id` que não existe responde hoje `200` com corpo vazio, sem `404`. Trate corpo vazio como "cobrança não encontrada". Confira também se a chave é do mesmo ambiente da cobrança: a chave de teste só enxerga cobranças de teste. ### `POST /v1/refunds` | HTTP | Mensagem | Causa | Ação | | - | - | - | - | | `404` | `Cobrança não encontrada` | `chargeId` inexistente, ou cobrança que não está `paid` (já estornada, pendente, `pre_chargeback` ou `chargeback`) | Consultar a cobrança antes de pedir o estorno | | `422` | `Já existe um reembolso para esta cobrança` | Segundo pedido de estorno para a mesma cobrança | Não repetir. Cada cobrança aceita um único estorno | | `501` | `Reembolso não implementado para este método de pagamento` | O método da cobrança não tem estorno pela API | Falar com o suporte | | `501` | `Reembolso não disponível para este provedor de pagamento` | O provedor da cobrança não oferece estorno | Falar com o suporte | | `500` | `Internal server error` | Erro interno | Consultar a cobrança antes de repetir | ### `POST /v1/charges/{id}/resend-webhook` | HTTP | Mensagem | Causa | Ação | | - | - | - | - | | `400` | Lista em `message` | `status` fora da lista aceita (`paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`). `pre_chargeback` e `chargeback` não são aceitos | Usar um dos status aceitos | | `403` | `Redisparo de webhook disponível apenas para cobranças de teste` | A cobrança foi criada com chave de produção | Usar uma cobrança criada com chave `sk_test_` | | `403` | `Acesso negado` | Perfil sem permissão | Ver erros comuns | | `404` | `Cobrança não encontrada` | `id` inexistente | Conferir o `id` | ## Apple Pay (domínios e sessão) Erros de negócio no formato `{ code, message }`. Erros de validação de campo vêm no formato padrão, com `message` em lista, e o `403` de permissão traz `Acesso negado`. | Rota | HTTP | Código | Causa | Ação | | - | - | - | - | - | | `POST /v1/apple-pay/domains` | `400` | `APPLE_PAY_INVALID_DOMAIN` | `domain` não é um hostname puro (tem esquema, porta, caminho, é um IP ou passa de 255 caracteres) | Enviar só o hostname, como `checkout.minhaloja.com.br` | | `POST /v1/apple-pay/domains` | `409` | `APPLE_PAY_DOMAIN_ALREADY_REGISTERED` | Dois registros simultâneos do mesmo hostname | Repetir a chamada: a rota devolve o registro existente | | `POST /v1/apple-pay/domains` | `400` | `APPLE_PAY_PROVIDER_REJECTED` | O provedor recusou o registro | Verificar o hostname e tentar de novo | | `POST /v1/apple-pay/domains` | `403` | `Acesso negado` | O usuário dono da chave não tem a permissão de domínios Apple Pay (Owner, Manager e Desenvolvedor têm) | Usar a chave de um desses perfis | | `POST /v1/apple-pay/domains/{id}/validate` | `404` | `APPLE_PAY_DOMAIN_NOT_FOUND` | Domínio inexistente ou de outra conta | Conferir o `id` com `GET /v1/apple-pay/domains` | | `POST /v1/apple-pay/domains/{id}/validate` | `422` | `APPLE_PAY_DOMAIN_VERIFICATION_FAILED` | Arquivo de verificação ausente ou inacessível. O domínio vai para `failed`, `verifiedAt` volta a `null` e o motivo fica em `lastVerificationError` | Corrigir a hospedagem do arquivo e validar de novo | | `GET /v1/apple-pay/domains/{id}` | `404` | `APPLE_PAY_DOMAIN_NOT_FOUND` | Domínio inexistente ou de outra conta | Conferir o `id` | | `POST /v1/apple-pay/validate-merchant` | `400` | `APPLE_PAY_INVALID_VALIDATION_URL` | `validationUrl` não é HTTPS em host `apple.com` (ou subdomínio), tem porta ou passa de 2048 caracteres | Enviar o `event.validationURL` recebido da Apple sem alterar | | `POST /v1/apple-pay/validate-merchant` | `400` | `APPLE_PAY_INVALID_DOMAIN` | `domain` inválido | Enviar o `window.location.hostname` | | `POST /v1/apple-pay/validate-merchant` | `400` | `APPLE_PAY_DOMAIN_NOT_VERIFIED` | O domínio não é da conta da `pk_`, não foi registrado ou ainda não foi verificado | Registrar e verificar o hostname exato da página | | `POST /v1/apple-pay/validate-merchant` | `422` | `APPLE_PAY_PROVIDER_NOT_ENABLED` | A conta ainda não registrou nenhum domínio | Registrar o primeiro domínio | | `POST /v1/apple-pay/validate-merchant` | `429` | `APPLE_PAY_RATE_LIMITED` | Mais de 20 tentativas por IP a cada 5 minutos, ou teto global da plataforma | Aguardar e validar uma vez por clique | | Todas as rotas de Apple Pay | `422` | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | Processador de Apple Pay não configurado para a conta | Falar com o suporte | | Todas as rotas de Apple Pay | `503` | `APPLE_PAY_PROVIDER_UNAVAILABLE` | Provedor indisponível | Tentar de novo mais tarde | | Todas as rotas de Apple Pay | `500` | `APPLE_PAY_PROVIDER_AUTH_FAILED` | Falha de autenticação entre a Finvia e o provedor | Falar com o suporte | ## Saldos e meios de pagamento | Rota | HTTP | Mensagem | Causa | Ação | | - | - | - | - | - | | `GET /v1/wallets` | `403` | `Acesso negado` | Chave de usuário Desenvolvedor | Gerar a chave com usuário Owner ou Manager | | `GET /v1/wallets` | `404` | `Merchant not found` (corpo `{ "statusCode": 404, "message": "Merchant not found", "error": "Not Found" }`) | `merchantId` inexistente ou sem acesso | Conferir o `merchantId` | | `GET /v1/payment-methods` | `401` | `Unauthorized` | Credencial inválida | Ver erros comuns | ## Saques Não existe saque no Modo Teste. Os erros de regra vêm em inglês. ### `POST /v1/payout-requests` (própria conta) | HTTP | Mensagem | Causa | Ação | | - | - | - | - | | `400` | Lista em `message` | Corpo inválido (campo ausente, tipo errado) | Corrigir o corpo. Não é `422` | | `400` | Lista em `message` | `currency` com código ISO inválido | Enviar `BRL` | | `403` | `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Pedido com a chave de teste | Saques só em produção | | `403` | `Acesso negado` | Chave de perfil sem permissão de saque (ex.: Desenvolvedor) | Gerar a chave com usuário Owner ou Manager | | `404` | `Merchant not found` | `merchantId` inexistente | Enviar o id da própria conta | | `422` | `Insufficient balance. Required: X, Available: Y` | Saldo disponível menor que `amount` | Consultar o saldo antes de sacar | | `422` | `Maximum withdrawal amount is X` | Valor acima do limite máximo por saque configurado para a conta | Dividir o saque ou falar com o suporte | | `422` | `You already have a pending withdrawal request for this currency` | Já existe um saque `pending` na mesma moeda | Aguardar a decisão do saque pendente | | `422` | `Withdrawals are disabled for this merchant` | Saques desabilitados na conta | Falar com o suporte | | `422` | `Saques estão desabilitados para esta conta (saldo retido por configuração administrativa)` | Conta com saldo retido | Falar com o suporte | | `422` | `Merchant account is not active` | Conta não está ativa | Falar com o suporte | | `422` | `Merchant settings are not configured correctly` | Configuração da conta incompleta | Falar com o suporte | | `422` | `Payout fees not configured` | Taxa de saque não configurada | Falar com o suporte | | `422` | `Currency X is not supported for withdrawals` | Moeda válida, mas sem saque | Enviar `BRL` | | `422` | `You can only create withdrawal requests for your own account` | `merchantId` de outra conta | Enviar o id da própria conta | | `422` | `Payout execution failed: ...` | Falha na execução, só em contas com aprovação automática | Consultar `GET /v1/payout-requests` antes de repetir: o pedido pode ter ficado `pending` | ### `POST /v1/submerchants/{merchantId}/payout-requests` (subconta) | HTTP | Mensagem | Causa | Ação | | - | - | - | - | | `400` | Lista em `message`, ex.: `["amount must be a positive number", "amount must not be less than 1"]` | `amount` ausente, zero ou abaixo de `1` | Enviar o valor em reais, mínimo `1` | | `403` | `Fast Connect not enabled.` | Connect não habilitado na conta master | Pedir a habilitação | | `403` | `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Pedido com a chave de teste | Saques só em produção | | `404` | `SubMerchant not found` | Subconta inexistente ou de outra conta master | Conferir o `merchantId` | | `422` | `SubMerchant account is not active` | Subconta não está `active` | Aguardar a aprovação da subconta | | `422` | `SubMerchant is blocked. Withdrawals are not allowed.` | Subconta bloqueada | Falar com o suporte | | `422` | `SubMerchant CNPJ not configured` | Subconta sem CNPJ cadastrado (o CNPJ é a chave Pix do saque) | Completar o cadastro da subconta | | `422` | `Withdrawals are disabled for this submerchant` | Saques desabilitados na subconta | Falar com o suporte | | `422` | `Insufficient balance. Required: X, Available: Y` | Saldo disponível insuficiente | Consultar o saldo antes de sacar | | `422` | `Maximum withdrawal amount is X BRL` | Valor acima do limite por saque | Dividir o saque | | `422` | `You already have a pending withdrawal request for this currency` | Já existe saque `pending` | Aguardar a decisão | | `422` | `Merchant settings are not configured correctly` | Configuração incompleta | Falar com o suporte | | `422` | `Payout fees not configured` | Taxa de saque não configurada | Falar com o suporte | ### `GET /v1/payout-requests` | HTTP | Mensagem | Causa | Ação | | - | - | - | - | | `403` | `Acesso negado` | Chave de usuário Desenvolvedor | Gerar a chave com usuário Owner ou Manager | | `404` | `Merchant not found` | `merchantId` de uma conta sem acesso | Conferir o `merchantId` | | `500` | `Internal server error` | `orderBy` enviado na consulta | Não envie `orderBy`: a ordem já é do mais recente para o mais antigo | ## Clientes | Rota | HTTP | Mensagem | Causa | Ação | | - | - | - | - | - | | `GET /v1/customers/{id}` | `404` | `Customer not found` | `id` inexistente ou de outra conta | Conferir o `id` | | `PUT /v1/customers/{id}` | `404` | `Customer not found` | `id` inexistente | Conferir o `id` | | `DELETE /v1/customers/{id}` | `404` | `Customer not found` | `id` inexistente ou já removido | Conferir o `id` | ## Cartões | Rota | HTTP | Mensagem | Causa | Ação | | - | - | - | - | - | | `POST /v1/cards` | `400` | `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 dígitos (CPF) nem 14 (CNPJ) | Usar um cliente com e-mail e CPF ou CNPJ | | `POST /v1/cards` | `400` | `Failed to register card` | Dados do cartão inválidos ou outra falha no registro | Conferir os dados do cartão | | `GET /v1/cards/{id}` | `404` | `Card not found` | `id` inexistente | Conferir o `id` | | `DELETE /v1/cards/{id}` | `404` | `Card not found` | `id` inexistente | Conferir o `id` | ## 3D Secure As rotas abaixo usam a **chave pública** (`pk_`). | Rota | HTTP | Mensagem | Causa | Ação | | - | - | - | - | - | | `/v1/three-ds/*` | `401` | `Unauthorized` | Chave pública inválida | Usar a `pk_` da conta (ou `pk_test_` no sandbox) | | `/v1/three-ds/*` | `404` | `No 3DS provider configured for this gateway` | Não há provedor 3DS configurado | Falar com o suporte para habilitar o 3DS | | `POST /v1/three-ds/challenge-result` | `500` | Mensagem iniciada por `Authentication challenge not yet completed` | Chamada antes do fim do desafio | Chamar só depois do sinal de fim do desafio ou de um status final | | `POST /v1/charges/{id}/resume-3ds` | `400` | `Cobrança não está utilizando 3DS gerenciado` | A cobrança não usa o 3DS gerenciado | Não chamar esta rota fora do fluxo gerenciado | | `POST /v1/charges/{id}/resume-3ds` | `400` | Lista em `message` | `threeDS` ausente, `null` ou com `type` ou `state` `null` | Enviar o objeto `threeDS` completo | | `POST /v1/charges/{id}/resume-3ds` | `404` | `Cobrança não encontrada ou não está aguardando autenticação` | A cobrança não está em `authentication_required` ou é de outra conta | Consultar a cobrança antes de retomar | | `POST /v1/charges/{id}/resume-3ds` | `422` | `Dados do cartão não encontrados. Crie uma nova cobrança.` | Os dados do cartão não estão mais disponíveis | Criar uma nova cobrança | | `POST /v1/charges/{id}/resume-3ds` | `422` | `Dados do cartão expiraram. Crie uma nova cobrança.` | Passaram os 15 minutos de guarda dos dados do cartão | Criar uma nova cobrança | | `POST /v1/charges/{id}/resume-3ds` | `422` | `Dados de autenticação expiraram. Crie uma nova cobrança.` | A autenticação terminou depois do prazo | Criar uma nova cobrança. A anterior não é processada | ## Planos de assinatura Todas as rotas de planos respondem `403` com `Acesso negado` para chaves de Desenvolvedor e Financeiro. O Visualizador só acessa as consultas (`GET`). | Rota | HTTP | Mensagem | Causa | Ação | | - | - | - | - | - | | `POST /v1/subscription-plans` | `400` | `Invalid payment methods: ...` | Método desconhecido em `paymentMethods` | Usar só os métodos aceitos | | `POST /v1/subscription-plans` | `404` | `Merchant not found` | O `merchantId` do corpo não é de uma conta a que a chave tem acesso | Conferir o `merchantId` | | `POST /v1/subscription-plans` | `404` | `Currency not found` | Moeda inexistente | Usar `BRL` | | `GET /v1/subscription-plans/{id}` | `404` | `Subscription plan not found` | `id` inexistente | Conferir o `id` | | `PUT /v1/subscription-plans/{id}` | `404` | `Subscription plan not found` | `id` inexistente | Conferir o `id` | | `POST /v1/subscription-plans/{id}/image` | `404` | `Subscription plan not found` | `id` inexistente | Conferir o `id` | | `PATCH /v1/subscription-plans/{id}/status` | `404` | `Subscription plan not found` | `id` inexistente | Conferir o `id` | | `PATCH /v1/subscription-plans/{id}/status/confirm` | `400` | `Invalid or expired confirmation token` | Token errado, vencido (vale 5 minutos) ou substituído por um pedido de desativação mais novo | Pedir a desativação de novo e confirmar dentro do prazo | | `PATCH /v1/subscription-plans/{id}/status/confirm` | `404` | `Subscription plan not found` | Plano inexistente ou de outra conta | Conferir o `id` | ## Assinaturas Todas as rotas de assinaturas respondem `403` com `Acesso negado` para chaves de Desenvolvedor e Financeiro. O Visualizador só acessa as consultas (`GET`). | Rota | HTTP | Mensagem ou código | Causa | Ação | | - | - | - | - | - | | `POST /v1/subscriptions` | `400` | `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | O cartão vai em `paymentMethod` e o cliente não tem e-mail ou CPF/CNPJ. Vale o documento do cliente já cadastrado com o mesmo e-mail | Usar um cliente com e-mail e CPF ou CNPJ | | `POST /v1/subscriptions` | `400` | `Failed to create subscription` | Dados inválidos ou falha na criação | Conferir o corpo, o cartão e o cliente | | `POST /v1/subscriptions` | `404` | `Subscription plan not found or inactive` | Plano inexistente ou com status `inactive` | Conferir o `subscriptionPlanId` e o status do plano | | `POST /v1/subscriptions` | `422` | `CARD_VALIDATION_FAILED`, com `message` `Não foi possível validar o cartão: ` | Plano com trial grátis: a validação de R\$ 1,00 foi recusada, ficou em análise ou não teve resposta. Nada é criado | Pedir outro cartão. A `message` pode ser exibida ao comprador | | `POST /v1/subscriptions` | `409` | `CARD_VALIDATION_IN_PROGRESS` | Já há uma validação do mesmo cartão em andamento (requisição repetida em paralelo) | Aguardar a primeira terminar | | `POST /v1/subscriptions` | `429` | `CARD_VALIDATION_RATE_LIMITED` | 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na mesma conta em 1 hora | Aguardar e pedir outro cartão | | `GET /v1/subscriptions/{id}` | `404` | `Subscription not found` | `id` inexistente | Conferir o `id` | | `PATCH /v1/subscriptions/{id}` | `400` | `Only active subscriptions can be updated` | A assinatura não está `active` (inclusive `pending_activation`) | Atualizar só assinaturas ativas | | `PATCH /v1/subscriptions/{id}` | `404` | `Subscription not found` | `id` inexistente | Conferir o `id` | | `POST /v1/subscriptions/{id}/cancel` | `400` | `Subscription already cancelled or expired` | A assinatura já está `cancelled` ou `expired` | Não repetir o cancelamento | | `POST /v1/subscriptions/{id}/cancel` | `404` | `Subscription not found` | `id` inexistente | Conferir o `id` | ## Connect As rotas do Connect respondem `403` com `Fast Connect not enabled.` quando o módulo não está habilitado na conta master. ### Subcontas | Rota | HTTP | Mensagem | Causa | Ação | | - | - | - | - | - | | `POST /v1/submerchants` | `400` | Lista em `message`, ex.: `["bankAccount.bankCode should not be empty"]` ou `["address.country must be a valid ISO31661 Alpha3 code"]` | Campo obrigatório ausente ou inválido. Com país `BRA`, CNPJ, UF, CEP e bairro também são validados | Corrigir os campos indicados. País em 3 letras (`BRA`) | | `POST /v1/submerchants` | `400` | `Email already registered` | `canAccessDashboard` é `true` e o e-mail do usuário do painel já existe | Usar outro e-mail para o usuário | | `POST /v1/submerchants` | `409` | `Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.` | O CNPJ já existe entre as subcontas da mesma master (em qualquer status) ou é o CNPJ da própria master | Consultar a subconta existente com `GET /v1/submerchants?search=` | | `POST /v1/submerchants` | `500` | `Internal server error` | Erro interno | Listar as subcontas antes de repetir | | `GET /v1/submerchants` | `400` | Lista em `message` | Valor de `status` fora dos 7 aceitos | Usar `active`, `inactive`, `pending`, `pre_approved`, `correcting`, `rejected` ou `blocked` | | `GET /v1/submerchants` | `500` | `Internal server error` | `orderBy` com nomes em camelCase (ex.: `legalName,-createdAt`) | Usar snake\_case: `legal_name,-created_at` | | `GET /v1/submerchants/{id}/api-keys` | `404` | `API keys not found for this submerchant.` | A API não encontrou chaves para a subconta | Conferir o `id` e o status da subconta | ### Documentos e representantes | Rota | HTTP | Mensagem ou código | Causa | Ação | | - | - | - | - | - | | `POST /v1/submerchants/{id}/document` | `400` | `Validation failed (current file type is text/plain, expected type is ...)` | Tipo de arquivo não aceito | Enviar PDF ou imagem (JPG, PNG, GIF, BMP ou WebP) | | `POST /v1/submerchants/{id}/document` | `400` | `File is required` | Nenhum arquivo enviado | Enviar o arquivo em `multipart/form-data` | | `POST /v1/submerchants/{id}/document` | `400` | Mensagem padrão de validação | Arquivo acima de 50 MB | Reduzir o arquivo | | `POST /v1/submerchants/{id}/document` | `400` | `Invalid document name` | Nome de campo fora da lista de documentos | Usar um dos seis nomes aceitos: `social_contract`, `cnpj_card`, `responsible_document_front`, `responsible_document_back`, `selfie_with_document` ou `irs_letter` | | `POST /v1/submerchants/{id}/document` | `400` | `Bad Request` | A subconta não pertence à conta master | Conferir o `id` | | `POST /v1/submerchants/{id}/document` | `422` | `Unprocessable Entity` (corpo `{ "statusCode": 422, "message": "Unprocessable Entity" }`) | Subconta já aprovada: os documentos não podem mais ser alterados | Falar com o suporte | | `POST /v1/submerchants/{merchantId}/document/upload-token` | `404` | `Representante legal não encontrado` | O `legalRepresentativeId` não pertence à subconta | Usar um `id` devolvido em `legalRepresentatives` ou na listagem de representantes | | `POST /v1/document-uploads` | `401` | Sem token, ou `Token de upload inválido ou expirado` | Token ausente, com assinatura inválida ou vencido (300 segundos) | Emitir um novo token e enviar logo em seguida | | `POST /v1/document-uploads` | `403` | `Token de upload expirado ou já utilizado` | Token de uso único já usado | Emitir um novo token | | `POST /v1/document-uploads` | `413` | `FILE_TOO_LARGE`: `O arquivo excede o tamanho máximo de 50 MB.` | Arquivo acima de 50 MB. `details` traz `maxMb` e `actualMb` | Reduzir o arquivo | | `POST /v1/document-uploads` | `415` | `UNSUPPORTED_FILE_TYPE`: `Tipo de arquivo não suportado. Envie PDF ou imagem (JPG, PNG, GIF, BMP ou WebP).` | Tipo não aceito. `details` traz `allowed` e `actualType` | Enviar PDF ou imagem aceita | | `POST /v1/document-uploads` | `400` | `NO_FILE_SENT`: `Nenhum arquivo foi enviado.` | Nenhum arquivo no `multipart/form-data` | Enviar o arquivo, com o nome do documento como nome do campo | | `POST /v1/document-uploads` | `400` | `INVALID_DOCUMENT_NAME`: `Tipo de documento inválido para este envio.` | Nome de campo fora da lista | Usar um dos nomes de documento aceitos | | `POST /v1/document-uploads` | `422` | `DOCUMENT_NOT_EDITABLE`: `Este documento não pode mais ser alterado no cadastro atual.` | Subconta já aprovada | Falar com o suporte | | `GET /v1/submerchants/{merchantId}/legal-representatives` | `400` | Lista em `message` | `include` com valor diferente de `documents` | Enviar `include=documents` ou omitir | | `GET /v1/submerchants/{merchantId}/legal-representatives` | `404` | `Merchant não encontrado` | A subconta não pertence à conta master autenticada | Conferir o `merchantId` | Em `POST /v1/document-uploads`, os erros de arquivo vêm no formato `{ "error": "", "message": "...", "details": { ... } }`, sem `statusCode`. Os erros do token (`401` e `403`) vêm no formato padrão. ### Taxas e dados da subconta | Rota | HTTP | Mensagem | Causa | Ação | | - | - | - | - | - | | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | `401` | `Não autorizado` | Credencial inválida | Ver erros comuns | | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | `403` | `Fast Connect não habilitado para esta conta` | Connect não habilitado na conta master | Pedir a habilitação do Connect | | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | `404` | `Subconta não encontrada` | `id` não vinculado à conta master, inexistente, ou o próprio id da conta master | Usar o `id` de uma subconta vinculada | ## Endpoints de webhook | Rota | HTTP | Mensagem | Causa | Ação | | - | - | - | - | - | | `POST` e `PUT /v1/webhook-endpoints` | `400` | `URL inválida: informe um endereço http(s) público (endereços internos e reservados não são permitidos)` | URL interna, reservada ou mal formada. Na validação do corpo, chega em lista em `message` | Usar um endereço público | | `POST` e `PUT /v1/webhook-endpoints` | `400` | `Este endereço é reservado e não pode ser usado como destino.` | Endereço reservado da plataforma | Usar outro endereço | | `POST` e `PUT /v1/webhook-endpoints` | `400` | `Apenas contas master com FastConnect habilitado podem receber eventos das subcontas` | `include_submerchants` em conta sem Connect | Retirar `include_submerchants` | | `POST` e `PUT /v1/webhook-endpoints` | `400` | Lista em `message` | Corpo inválido, como `enabled_events` que não é lista | Corrigir o corpo | | `POST /v1/webhook-endpoints` | `403` | `Apenas administradores do gateway podem configurar endpoints de nível gateway` | Chamada sem `merchantId` na query | Enviar `?merchantId=` com o id da conta | | Todas | `403` | `Acesso negado` | Conta sem acesso ao `merchantId`, ou perfil sem permissão de webhooks | Conferir o `merchantId` e o perfil de quem gerou a chave | | Todas | `404` | `Merchant não encontrado` | `merchantId` inexistente | Conferir o `merchantId` | | `PUT` e `DELETE /v1/webhook-endpoints/{webhookId}` | `404` | `Webhook não encontrado` | `webhookId` inexistente | Conferir o id na listagem | ## Veja também > [card] [Erros e como tratar](/primeiros-passos/erros) > > Formato das respostas e quando repetir. > [card] [Mapa da API](/mapa-da-api) > > Todas as rotas e sua autenticação. > [card] [Status de cobrança](/anexos/status-de-cobranca) > > Recusas, bloqueios e disputas. > [card] [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) > > Permissões da chave e autenticação. # Status de cobrança Source: https://docs.fastpaybrasil.com/anexos/status-de-cobranca Todos os status de cobrança em uma tabela, com o que significam, quando acontecem e o que o seu sistema deve fazer, além da marcação de bloqueio e dos status de estorno, assinatura, cartão, subconta e saque. O status diz em que ponto da vida um objeto está. Esta página reúne todos os status documentados da API, começando pela cobrança, que é o mais usado. Use-a como referência para decidir quando liberar um pedido, quando avisar o cliente e quando abrir um tratamento de disputa. > [!NOTE] > > **Para o negócio:** a regra mais segura é liberar pedido, envio ou acesso somente com a cobrança em `paid` e sem bloqueio (`isBlocked` diferente de `true`). Os demais status pedem espera, uma ação do cliente ou um tratamento de pós-venda, como mostram as tabelas. ## Status da cobrança Lista de valores do campo `status` em `POST /v1/charges`, `GET /v1/charges`, `GET /v1/charges/{id}` e nos webhooks de cobrança. | Status | Significado | Quando acontece | Pode mudar depois? | O que o merchant deve fazer | | - | - | - | - | - | | `pending` | Aguardando pagamento | Pix criado (o QR Code está disponível) ou cartão que o processador deixou pendente | Sim. Vai para `paid` quando o pagamento é confirmado, ou para `failed` ou `refused` (conforme o adquirente) se o Pix for cancelado ou expirar | Mostrar o QR Code e o copia e cola. Manter o pedido reservado. **Não liberar** | | `paid` | Pago com sucesso | Cartão aprovado na criação, Pix pago ou pagamento confirmado depois pelo adquirente | Sim. Pode ir para `refunded`, `pre_chargeback` ou `chargeback`, e pode receber bloqueio sem mudar de status | **Liberar o pedido**, enviar o produto ou dar acesso. Antes de ações de alto valor, confirmar com `GET /v1/charges/{id}` | | `refused` | Recusado | Cartão recusado, com o motivo em `reason` (ex.: `card_declined`, `antifraud_denied`). Também quando o 3DS obrigatório não foi concluído (`reason` começa com `3ds_`) | Trate como resultado final da tentativa | Não liberar. Mostrar mensagem amigável e oferecer outro cartão ou Pix. Guardar `reason` no log | | `failed` | Falha no processamento | Erro ao processar a cobrança. Em alguns adquirentes, também a recusa informada depois, o cancelamento e a expiração | Trate como resultado final da tentativa | Não liberar. Oferecer nova tentativa ou outro meio de pagamento | | `in_analysis` | Em revisão manual antifraude | Na criação, quando a análise antifraude manda a cobrança para revisão manual. A resposta traz `reason` `antifraud_manual_review` | Sim. Vai para `paid` se a análise aprovar, ou para `refused` ou `failed` se negar | Não liberar. Avisar o cliente que o pagamento está em análise. Acompanhar pelo `postbackUrl` ou por `GET /v1/charges/{id}`, porque a negativa só chega pelo `charge.updated` | | `authentication_required` | Aguardando o comprador concluir a autenticação | Na criação, quando a política de 3D Secure da conta dispara e o banco emissor pede verificação do dispositivo ou desafio. No 3DS gerenciado, vem com `reason` `Autenticação 3DS gerenciada necessária` e `paymentDetails: null`. Alguns adquirentes também devolvem este status quando exigem autenticação do lado deles | Sim. Segue para `paid`, `pending`, `refused` ou `failed` quando a página da `authenticationUrl` conclui a autenticação e retoma a cobrança. Se o comprador abandonar, a cobrança fica neste status, sem expiração automática e sem webhook | Levar o comprador ao endereço recebido em `authenticationUrl`, sem montar nem alterar a URL. Não liberar. Se a autenticação não terminar em 15 minutos, crie uma nova cobrança | | `refunded` | Estornado | Estorno total concluído (`charge.refunded`), alerta de pré-chargeback com estorno, contestação de Pix aceita ou reversão de saldo de um chargeback | Trate como final | Cancelar o pedido, revogar acesso e registrar a devolução | | `pre_chargeback` | Alerta de contestação recebido antes do chargeback formal | O portador contestou a compra junto ao emissor (`charge.pre_chargeback`) | Pode evoluir dentro da disputa | Se chegou `charge.refunded` ou `chargebackAlertRefunded: true`, tratar como **estornado**. Se não, tratar como **em disputa**, sem estorno | | `chargeback` | Chargeback formalizado | O adquirente informa a disputa de cartão. Aviso pelo `charge.updated` no `postbackUrl` | Trate como final | Registrar a perda, cancelar o pedido e acionar o fluxo interno de disputa. Confirmar com `GET /v1/charges/{id}` | ### Fluxos típicos | Forma de pagamento | Caminho comum | | - | - | | Pix | `pending` → `paid` → (opcional) `refunded` | | Cartão aprovado | `paid` → (opcional) `refunded`, `pre_chargeback` ou `chargeback` | | Cartão recusado | `refused` | | Cartão com 3D Secure com verificação ou desafio | `authentication_required` → `paid`, `pending`, `refused` ou `failed` | | Cartão em revisão antifraude | `in_analysis` → `paid`, `refused` ou `failed` | O desenho abaixo mostra como a cobrança sai da criação e chega a um resultado. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB S(["POST /v1/charges"]):::neutro AUT["authentication_required
aguardando o comprador"]:::alerta J(["cobrança
retomada"]):::neutro AN["in_analysis
em revisão antifraude"]:::alerta PEN["pending
aguardando pagamento"]:::alerta PAID(["paid
pago"]):::ok REF(["refused · failed
recusado ou falhou"]):::erro S -->|"3DS com verificação
ou desafio"| AUT S -->|"Pix criado ou
cartão pendente"| PEN S -->|"revisão manual"| AN S ==>|"cartão aprovado"| PAID S -->|"cartão recusado
ou erro"| REF AUT -->|"comprador conclui
na authenticationUrl"| J J --> PEN J --> PAID J --> REF PEN ==>|"pagamento confirmado"| PAID PEN -->|"Pix cancelado
ou expirado"| REF AN -->|"análise aprova"| PAID AN -->|"análise nega"| REF classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Se o comprador abandona a autenticação, a cobrança fica em `authentication_required`, sem expiração automática e sem webhook. ### Como o status chega até você | Status | Resposta da criação | Endpoints de webhook | `postbackUrl` da cobrança | | - | - | - | - | | `pending` | Sim | `charge.created` e `charge.pending` | `charge.created` e `charge.pending` | | `paid` | Sim (cartão aprovado na hora) | `charge.paid` | `charge.paid` e, quando o adquirente informa o pagamento, `charge.updated` | | `refused`, `failed` na criação ou no fim do 3DS gerenciado | Sim, na criação | `charge.refused` ou `charge.failed` | `charge.refused` ou `charge.failed` e, no 3DS gerenciado, `charge.updated` | | `refused`, `failed` informados depois pelo adquirente | Não | Nada | Só `charge.updated` | | `in_analysis` | Sim | Só `charge.created` | Só `charge.created` | | `authentication_required` | Sim, com `authenticationUrl` | Só `charge.created` | Só `charge.created` | | `refunded` | Não | `charge.refunded` | `charge.refunded` e, quando vem do adquirente, `charge.updated` | | `pre_chargeback` | Não | `charge.pre_chargeback` (e `charge.refunded`, se houve estorno) | Os mesmos eventos, mais `charge.updated` | | `chargeback` | Não | `charge.refunded`, só quando a reversão devolve o valor do saldo | `charge.updated` com `status: "chargeback"` e, quando há reversão de saldo, `charge.refunded` | Formato dos eventos: [Catálogo de eventos](/anexos/catalogo-de-eventos). ## Bloqueio (`isBlocked`) O bloqueio é uma **marcação**, separada do status. Uma cobrança bloqueada continua `paid` e passa a ter `isBlocked: true`, `blockedAt` e `blockedReason` (no envelope padrão do webhook, `is_blocked`, `blocked_at` e `blocked_reason`). Na API não existe status nem evento chamado MED ou chargeback em análise: o integrador vê essa marcação. | Ponto | Como funciona | | - | - | | Quem aplica | A equipe da Finvia, e só em cobranças `paid`. O bloqueio não chega automaticamente do banco | | Aviso | `charge.blocked` aos endpoints e ao `postbackUrl`. Quem tem `postbackUrl` recebe também o `charge.updated` | | Saldo | O que a venda já liquidou (o líquido mais as taxas da venda) sai do saldo disponível e vai para o saldo bloqueado. Parcelas que liquidarem durante o bloqueio também caem no saldo bloqueado | | `blockedReason` | Texto livre preenchido pela Finvia. Pode indicar MED ou chargeback e pode vir vazio | | Como saber se está bloqueada | Leia `isBlocked`. Na liberação, `blockedReason` é apagado, mas `blockedAt` continua preenchido | | Listar bloqueadas | `GET /v1/charges?status=blocked` | | Liberação | Volta `isBlocked: false` e **não gera webhook nem postback**. Confirme por `GET /v1/charges/{id}` | ### MED e chargeback | | MED (Mecanismo Especial de Devolução) | Chargeback | | - | - | - | | Meio de pagamento | Só Pix | Só cartão | | Na API | Bloqueio da cobrança (`isBlocked: true`, `charge.blocked`), status continua `paid` | Pode começar com alerta de pré-chargeback (`pre_chargeback`) e bloqueio. A formalização muda o status para `chargeback` | | Desfecho a favor do merchant | Liberação do bloqueio: `isBlocked: false`, sem webhook | Liberação do bloqueio: `isBlocked: false`, sem webhook | | Desfecho contra o merchant | Contestação aceita: estorno, status `refunded` e `charge.refunded` | Status `chargeback`, informado pelo adquirente. Aviso por `charge.updated` no `postbackUrl` e, se a reversão devolver o valor do saldo, `charge.refunded`. Se a cobrança já tinha sido estornada no pré-chargeback, só o `charge.updated` | O MED é diferente do bloqueio cautelar do Pix, que é outra ferramenta: uma retenção preventiva e curta feita pela instituição do recebedor quando suspeita de fraude. Na API, os dois aparecem da mesma forma, como bloqueio da cobrança. O desenho abaixo mostra o que pode acontecer com uma cobrança depois de paga, inclusive o bloqueio, que não muda o status. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB PAID(["paid
pago"]):::ok BLQ["bloqueada: isBlocked true
o status segue paid"]:::alerta LIB(["liberada, segue paid
isBlocked false
sem webhook"]):::ok PRE["pre_chargeback
alerta de contestação"]:::alerta RFD(["refunded
estornado"]):::neutro CB(["chargeback
formalizado"]):::erro PAID -->|"estorno total"| RFD PAID -->|"Finvia bloqueia
MED ou disputa"| BLQ PAID -->|"portador contesta
no emissor"| PRE PAID -->|"adquirente informa
a disputa"| CB BLQ -->|"bloqueio retirado"| LIB BLQ -->|"Pix: contestação
aceita"| RFD BLQ -->|"cartão: chargeback
perdido"| CB PRE -->|"alerta com estorno"| RFD PRE -->|"disputa
formalizada"| CB classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` **1. Bloqueio recebido** Ao receber `charge.blocked` (ou `charge.updated` com `isBlocked: true`), identifique a cobrança por `data.id` e marque o pedido como "em disputa". **2. Defesa** Não existe rota de API para enviar defesa de MED ou de chargeback. O alerta de chargeback ou MED chega por e-mail à conta (no Connect, à conta master), e a defesa com as evidências é enviada em resposta a esse e-mail, dentro do prazo indicado nele. Dúvidas, pelo suporte. Detalhes em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). **3. Desfecho** Como a liberação não gera aviso, consulte periodicamente `GET /v1/charges/{id}` das cobranças em disputa. `isBlocked: false`: restaure o pedido. `status` `refunded` ou `chargeback`: registre a perda e acione o cancelamento. > [!WARNING] > > O status `chargeback` e as recusas assíncronas chegam só pelo `charge.updated`, que vai **somente** para o `postbackUrl` da cobrança. No chargeback, os endpoints recebem apenas o `charge.refunded`, e só quando o valor é revertido do saldo. Se a sua integração não informa `postbackUrl`, acompanhe essas cobranças por `GET /v1/charges/{id}`. ## Status do estorno Resposta de `POST /v1/refunds`. É o status da **operação de estorno**, separado do status da cobrança. | Status | Significado | O que fazer | | - | - | - | | `refunded` | O estorno foi registrado na Finvia e o valor saiu do saldo do lojista. A cobrança passa a `refunded` e `charge.refunded` é enviado | Registrar a devolução. Não reenviar o pedido de estorno | Hoje a API devolve só `refunded`. Prazos, casos especiais e o que fazer se o comprador não receber estão em [Estorno](/guias/estorno). ## Status da assinatura Campo `status` de `POST /v1/subscriptions`, `GET /v1/subscriptions`, `GET /v1/subscriptions/{id}` e dos webhooks `subscription.*`. Na criação, os status possíveis são `active` e `pending_activation`. | Status | Significado | O que o merchant deve fazer | | - | - | - | | `pending_activation` | A primeira cobrança foi recusada ou está em análise. A assinatura não está ativa, não cobra, não renova e não tem retentativa automática. Se a análise aprovar o pagamento, passa a `active` automaticamente | Não liberar acesso. Se recusada, criar uma nova assinatura (por exemplo, com outro cartão) e, se quiser, cancelar a pendente. Se em análise, aguardar `subscription.activated` ou `subscription.payment_failed` | | `active` | Ativa e em dia. Continua `active` durante as retentativas de renovação | Manter o acesso. A cada `subscription.payment_failed`, avisar o cliente | | `cancelled` | Cancelada. Novas cobranças não são feitas | Arrependimento (`regret`): revogar acesso imediatamente. Regular (`regular`): manter acesso até `current_period_end` | | `expired` | Encerrada por esgotar as retentativas do ciclo ou porque o plano chegou ao `endDate` | Revogar o acesso | O desenho abaixo mostra o ciclo de vida da assinatura. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB S(["POST /v1/subscriptions"]):::neutro PA["pending_activation
não cobra nem renova"]:::alerta AC["active
ativa e em dia"]:::ok RT["Renovação recusada
retentativas, segue active"]:::alerta CA(["cancelled
cancelada"]):::neutro EX(["expired
encerrada"]):::erro S -->|"primeira cobrança
aprovada ou trial"| AC S -->|"primeira cobrança
recusada ou em análise"| PA PA -->|"análise aprova"| AC PA -->|"cancelamento"| CA AC -->|"cancelamento"| CA AC -->|"cobrança do ciclo
recusada"| RT RT -.->|"retentativa
aprovada"| AC RT -->|"tentativas
esgotadas"| EX AC -->|"endDate
do plano"| EX classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Uma assinatura em `pending_activation` com a primeira cobrança recusada não é cobrada de novo. Para tentar outro cartão, crie uma nova assinatura. ### Status da cobrança dentro da assinatura No histórico `charges` de `GET /v1/subscriptions/{id}`. Há uma linha por tentativa: as retentativas recusadas de um ciclo repetem o mesmo `billingCycle`. | Status | Significado | | - | - | | `pending` | Em análise | | `paid` | Paga com sucesso | | `failed` | Falhou | | `refunded` | Estornada | ## Status do cartão salvo Os valores dependem da rota. | Status | Onde aparece | Significado | | - | - | - | | `active` | Listagem e consulta | Pronto para uso. Com o processador atual, todo cartão nasce `active` | | `expired` | Listagem e consulta | A validade do cartão passou | | `revoked` | Listagem e consulta | O cartão foi excluído com `DELETE /v1/cards/{id}` | | `inactive` | Só na consulta (`GET /v1/cards/{id}`) | A assinatura que usava o cartão foi cancelada e nenhuma outra o usa. Volta a `active` se o cliente assinar de novo com ele | | `pending_validation` | Só na consulta | Só em cartões antigos do processador anterior | Para saber se um cartão pode ser usado em `POST /v1/charges`, use a listagem `GET /v1/cards`: a cobrança recusa cartão `revoked` ou `expired`. ## Status da subconta (Connect) Campo `status` de `GET /v1/submerchants` e `GET /v1/submerchants/{merchantId}`. Só a subconta `active` opera. | Status | Significado | Gera aviso de status de conta? | O que fazer | | - | - | - | - | | `pending` | Cadastro recebido, em análise. Também depois que uma correção é reenviada | Não | Enviar todos os documentos e aguardar | | `pre_approved` | Documentos obrigatórios conferidos. A subconta está sendo credenciada nas adquirentes e aguarda a aprovação final | Sim | Aguardar a aprovação final | | `correcting` | A Finvia pediu correção de dados ou documentos. Só acontece a partir de `pending` ou `pre_approved`. O motivo vem em `rejectionReason` | Sim | Corrigir pelo painel, na gestão de subcontas. A correção não é feita pela API | | `active` | Aprovada e apta a transacionar | Sim, na aprovação e no desbloqueio | Liberar vendas e obter as chaves da subconta | | `rejected` | Reprovada. Motivo em `rejectionReason` | Sim | Informar o vendedor | | `blocked` | Bloqueada | Sim | Suspender as vendas da subconta até o desbloqueio | | `inactive` | Inativada | Não | Encerrar a operação do vendedor | Fluxo comum: `pending` → `pre_approved` → `active`. Pedidos de correção levam a `correcting`, e a conta volta a `pending` quando os dados são reenviados. O aviso de status vai para a URL de aviso de status da subconta, como explica [Webhooks de conta](/guias/webhooks/conta). O desenho abaixo mostra o fluxo comum de aprovação da subconta e o ciclo de correção. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB P["pending
em análise"]:::alerta PRE["pre_approved
documentos conferidos"]:::alerta A(["active
pode vender"]):::ok C["correcting
correção pedida"]:::alerta P -->|"documentos
conferidos"| PRE PRE -->|"aprovação final"| A P -->|"Finvia pede
correção"| C PRE -->|"Finvia pede
correção"| C C -->|"dados reenviados
pelo painel"| P classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Os status `rejected`, `blocked` e `inactive` estão na tabela acima. ## Status do saque Status de uma solicitação de saque, da própria conta ou de subconta. | Status | Significado | O que fazer | | - | - | - | | `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda decisão | Aguardar | | `approved` | Aprovado e enviado para pagamento. Nos saques de subconta, gera o webhook `payout.approved` | Registrar o valor líquido (`netAmount`) | | `rejected` | Rejeitado. O valor volta ao saldo disponível e o motivo fica em `rejectionReason`. Nos saques de subconta, gera o webhook `payout.rejected` | Informar o solicitante e corrigir a causa | Só os saques de subconta geram webhook. O saque da própria conta é acompanhado pela [listagem de saques](/referencia/saques/listar). ## Status do plano de assinatura | Status | Significado | | - | - | | `active` | Disponível para novas assinaturas | | `inactive` | Indisponível para novas assinaturas. As assinaturas existentes continuam renovando normalmente | ## Veja também > [card] [Catálogo de eventos](/anexos/catalogo-de-eventos) > > Todos os eventos de webhook e seus formatos. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > Como funciona a disputa e a defesa. > [card] [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida) > > Renovação, retentativa e cancelamento. > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Cadastro e aprovação de subcontas. # Cobrança por mensagem Source: https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link Venda fechada pelo WhatsApp, Instagram ou telefone: o seu sistema gera um Pix pela API, envia o copia e cola por mensagem e recebe a confirmação por webhook. Muita venda acontece sem carrinho de compras: o cliente pergunta pelo WhatsApp, combina pelo direct do Instagram ou fecha por telefone. Nesses casos, o vendedor precisa mandar um jeito de pagar dentro da própria conversa e saber, sem conferir o extrato, quando o pagamento entrou. Esta página mostra como fazer isso com uma cobrança Pix criada pela API. > [!WARNING] > > **A API da Finvia não tem um recurso de "link de pagamento" hospedado.** Não existe uma rota que devolva uma página pronta para o cliente pagar. Quem monta a mensagem é o **seu sistema**, com o código copia e cola (`copyPaste`) e a imagem do QR Code (`qrCodeBase64`) que a API devolve na criação da cobrança Pix. Para receber em cartão, você precisa de uma página de checkout própria que colete os dados do cartão e chame a API pelo seu servidor. > [!TIP] > > Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](/integrar-com-ia). Implementar este caso com um assistente de IA Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link.md](https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link.md) * [https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/pix.md](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) * [https://docs.fastpaybrasil.com/guias/estorno.md](https://docs.fastpaybrasil.com/guias/estorno.md) * [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md) * [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar neste projeto o fluxo descrito na página "Cobrança por mensagem" ([https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link.md](https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link.md)). Resumo do caso: Venda fechada pelo WhatsApp, Instagram ou telefone: o seu sistema gera um Pix pela API, envia o copia e cola por mensagem e recebe a confirmação por webhook. Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## O cenário A **Doce Encontro Confeitaria** faz bolos e doces sob encomenda em Salvador. Todas as encomendas chegam pelo WhatsApp e pelo Instagram: cerca de 350 pedidos por mês, com ticket médio de R\$ 180. A confeitaria usa um pequeno sistema interno onde a atendente registra o pedido. Hoje, a atendente manda a chave Pix da empresa, o cliente paga, envia o comprovante por foto e alguém confere o extrato antes de liberar a produção. A Doce Encontro quer: * gerar uma cobrança Pix com o valor exato do pedido, direto do sistema interno; * enviar o copia e cola e o QR Code na conversa; * dar 2 dias para o cliente pagar; * saber automaticamente quando o pagamento entrou, sem pedir comprovante. ## O que a Finvia resolve > [!NOTE] > > **Para o negócio:** cada pedido vira uma cobrança Pix com valor, cliente e validade definidos. A API devolve o código copia e cola e a imagem do QR Code, que o sistema da confeitaria envia ao cliente. Quando o cliente paga, a Finvia envia um webhook (`charge.paid`) ao sistema, que marca o pedido como pago. Não é preciso conferir comprovante, porque a confirmação vem da Finvia. ## Arquitetura da solução | Necessidade | Recurso | Rota ou guia | | - | - | - | | Gerar o Pix do pedido | Cobrança Pix com `expirationInDays` | `POST /v1/charges` · [Pix](/guias/cobrancas/pix) | | Montar a mensagem | `paymentDetails.copyPaste` e `paymentDetails.qrCodeBase64` | Resposta de `POST /v1/charges` | | Saber que pagou | Webhook `charge.paid` | [Webhooks de cobrança](/guias/webhooks/cobranca) | | Saber que o Pix expirou | `charge.updated` no `postbackUrl` | [Webhooks de cobrança](/guias/webhooks/cobranca) | | Confirmar o status | Consulta da cobrança | `GET /v1/charges/{id}` | | Devolver o dinheiro | Estorno total | `POST /v1/refunds` · [Estorno](/guias/estorno) | O desenho abaixo mostra o caminho de uma encomenda da Doce Encontro, da conversa ao pedido pago. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB C(["Cliente
no WhatsApp ou Instagram"]):::comprador S["Sistema interno
atendente lança o pedido
chave secreta sk_"]:::lojista API["Finvia API"]:::finvia BC["Sistema Pix
cliente paga no app
do banco"]:::externo EV[["charge.paid"]]:::evento W["Receptor de webhooks
endpoint e postbackUrl"]:::lojista OK(["Pedido pago
entra na produção"]):::ok C -->|"1. encomenda
na conversa"| S S -.->|"4. envia o copia e cola
pela ferramenta
de atendimento"| C S ==>|"2. POST /v1/charges
pix · expirationInDays 2"| API API -.->|"3. 201 · copyPaste
e qrCodeBase64"| S API -->|"5. Pix válido por 2 dias"| BC API -->|"6. publica o evento"| EV EV -.->|"7. entrega"| W W ==>|"8. confere com
GET /v1/charges/{id}"| OK classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` A mesma cobrança em ordem, com os dois desfechos possíveis: pago dentro do prazo ou vencido. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Cliente end box rgb(243,245,248) Sua aplicação participant S as Sistema da confeitaria end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant B as Banco do cliente end C->>S: Encomenda bolo e brigadeiros pelo WhatsApp S->>F: POST /v1/charges (pix · expirationInDays 2) F-->>S: 201 · pending · copyPaste · qrCodeBase64 S-->>C: Mensagem com o valor e, separado, o copia e cola alt Cliente paga em até 2 dias C->>B: Cola o código em Pix copia e cola B->>F: Confirma o Pix F-)S: Webhook charge.paid S->>F: GET /v1/charges/{id} F-->>S: status paid S-->>C: Pagamento confirmado, pedido na produção else Prazo acabou sem pagamento F-)S: charge.updated no postbackUrl (failed) S->>F: GET /v1/charges/{id} no fim da validade S-->>C: Cancela a encomenda ou gera um Pix novo end ``` Os endpoints do painel não recebem aviso de expiração. Por isso o sistema também controla o prazo e consulta a cobrança no fim da validade. ## Passo a passo **1. Cadastre o endpoint de webhook** No painel (`https://app.finvia.com.br`), em **Configurações** > **Webhooks**, cadastre a URL do sistema interno, em HTTPS, por exemplo `https://pedidos.doceencontro.exemplo.com.br/webhooks/finvia`. Em cada cobrança, envie também um `postbackUrl` em outra URL, por exemplo `https://pedidos.doceencontro.exemplo.com.br/webhooks/finvia/postback`. Ele recebe os mesmos eventos e também o `charge.updated` legado, que avisa quando o Pix é cancelado ou expira. Se a mesma URL estiver nos dois lugares, ela recebe cada evento duas vezes. **2. Gere a cobrança Pix do pedido** A atendente registra a encomenda: bolo de chocolate de 2 kg e um cento de brigadeiros, R\$ 210,00 no total. O sistema cria a cobrança com validade de 2 dias: ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 210, "currency": "BRL", "customer": { "name": "Ana Lima", "phone": "+5511987654321" }, "paymentMethod": { "type": "pix", "expirationInDays": 2 }, "items": [ { "title": "Bolo de chocolate 2 kg", "type": "physical", "description": "Recheio de brigadeiro, retirada no sábado", "unit_price": 130, "quantity": 1 }, { "title": "Brigadeiro gourmet", "type": "physical", "description": "Cento", "unit_price": 80, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "metadata": { "pedido": "DE-3127", "canal": "whatsapp" }, "postbackUrl": "https://pedidos.doceencontro.exemplo.com.br/webhooks/finvia/postback" }' ``` Repare em `customer`: sem `id`, a API aceita `name` mais `email` **ou** `phone`. Como a conversa é pelo WhatsApp, o telefone basta. > [!NOTE] > > Os itens são `physical` porque a confeitaria vende produto físico. Com algum item `physical`, `shippingAddress` é obrigatório, mesmo quando o cliente retira na loja: nesse caso, a confeitaria usa o endereço de retirada ou o endereço do cliente, conforme a sua política. Sem o endereço, a API responde `400` com `Shipping info must be provided for merchants selling physical items.`. São obrigatórios `postalCode`, `addressLine1`, `city`, `state` e `country` (`BRA`); `addressLine2` e `neighborhood` são opcionais. O endereço desta página é fictício. **3. Monte a mensagem com o copia e cola** A resposta traz tudo o que a mensagem precisa: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "pending", "paymentDetails": { "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo..." }, "reason": null } ``` O sistema da confeitaria monta o texto e envia pelo canal da conversa: ```javascript theme={null} const mensagem = [ `Oi, ${pedido.nomeCliente}! Seu pedido ${pedido.codigo} ficou em R$ 210,00.`, 'Para pagar, copie o código Pix abaixo e cole no app do seu banco, em "Pix copia e cola":', '', cobranca.paymentDetails.copyPaste, '', 'O código vale por 2 dias. Assim que o pagamento entrar, a gente te avisa por aqui.', ].join('\n'); ``` O `copyPaste` vai em uma mensagem separada, sozinho, para o cliente copiar com um toque. Se quiser mandar também a imagem do QR Code, converta o `qrCodeBase64` (uma imagem PNG em data URI) em arquivo e envie como foto. Se `qrCodeBase64` vier `null`, envie só o copia e cola. > [!TIP] > > **Para o desenvolvedor:** o envio pelo WhatsApp ou Instagram é feito pelo seu sistema, pela ferramenta de atendimento que você já usa. A Finvia não envia mensagens ao cliente. Guarde o `id` da cobrança junto do pedido `DE-3127`. **4. Receba a confirmação por webhook** Quando o cliente paga, a Finvia envia `charge.paid` ao endpoint cadastrado e ao `postbackUrl`. O sistema confirma o status na API, marca o pedido como pago e avisa a cozinha. ```javascript theme={null} app.post('/webhooks/finvia', async (req, res) => { const { id, event, data } = req.body; if (id && (await eventos.jaProcessado(id))) return res.status(200).send('OK'); res.status(200).send('OK'); if (event === 'charge.paid') { const cobranca = await finvia.get(`/v1/charges/${data.id}`); if (cobranca.status === 'paid') { await pedidos.marcarComoPago(cobranca.metadata.pedido); await atendimento.enviarMensagem(cobranca.metadata.pedido, 'Pagamento confirmado! Seu pedido entrou na produção.'); } } if (id) await eventos.marcarProcessado(id); }); ``` Antes do `charge.paid`, chegam `charge.created` e `charge.pending`. Eles confirmam que a cobrança foi criada, e o sistema pode só registrá-los. **5. Trate o pedido não pago** Se o cliente não pagar em 2 dias, o código expira. Os endpoints do painel não recebem aviso de expiração. O `postbackUrl` recebe o `charge.updated` legado (em camelCase, sem `id` de evento), e o status final pode vir como `failed`. Mesmo assim, o sistema controla o prazo: ao fim da validade, ele consulta a cobrança com `GET /v1/charges/{id}`. Se ela não estiver `paid`, cancela a encomenda ou gera uma cobrança nova, se o cliente ainda quiser o pedido. **6. Devolva o dinheiro quando necessário** Se a confeitaria não puder atender uma encomenda já paga, ela faz o estorno total. No Pix, a devolução é enviada na hora para a conta de origem do cliente. Peça o estorno em até 90 dias do pagamento, que é o prazo das regras do Pix. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/refunds" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Encomenda DE-3127 cancelada pela confeitaria" }' ``` A resposta vem com `status` `refunded`, e o evento `charge.refunded` é enviado. Cada cobrança aceita um estorno: um segundo pedido recebe `422` "Já existe um reembolso para esta cobrança". ## Regras e cuidados > [!WARNING] > > **Não confie em comprovante enviado pelo cliente.** A confirmação válida é o status `paid` da cobrança na API. Uma foto de comprovante pode ser de outro pagamento, de outro valor ou editada. > [!WARNING] > > **Valor em reais.** `"amount": 210` é R\$ 210,00. Enviar `21000` gera uma cobrança de R\$ 21.000,00, e o cliente vai ver esse valor no app do banco. * **Validade.** Em cobrança por mensagem, use `expirationInDays` (mínimo `1`). `expirationInSeconds` aceita a partir de `900` (15 minutos), útil quando o cliente paga durante a conversa. * **Uma cobrança por pedido.** O código copia e cola é ligado a uma cobrança com valor fixo. Se o pedido mudar de valor, gere uma cobrança nova e avise o cliente para usar só o código novo. * **Cliente identificado.** Sem `customer.id`, envie `name` e `email` ou `phone`. O documento é opcional no Pix. * **Produto físico.** Com algum item `physical`, `shippingAddress` é obrigatório. Sem ele, a cobrança não é criada (`400`). * **Sem link hospedado.** Não existe rota de link de pagamento. Não tente montar uma URL de pagamento a partir do `copyPaste`. ## Variações do caso > [accordion] E se o cliente quiser pagar no cartão? > > Como a API não hospeda uma página de pagamento, a confeitaria precisa de uma página de checkout própria, em HTTPS, que colete os dados do cartão e envie ao servidor dela, que chama `POST /v1/charges` com `credit_card`. A mensagem do WhatsApp leva o endereço dessa página, com o código do pedido. A chave secreta nunca vai para o navegador. Se a página for usar 3D Secure, veja [3D Secure](/guias/3d-secure/visao-geral). > [accordion] E se a venda for de serviço, sem entrega? > > Para serviços (aula particular, consultoria, conserto já feito), use itens `digital`, sem `shippingAddress`. O restante do fluxo é igual. > [accordion] E se a venda for por telefone, com o cliente esperando na linha? > > Use `expirationInSeconds` com 15 a 30 minutos (`900` a `1800`) e envie o copia e cola por SMS ou WhatsApp enquanto a ligação continua. O atendente vê a confirmação no sistema assim que o `charge.paid` chega. > [accordion] E se o mesmo cliente comprar toda semana? > > Cadastre o cliente com `POST /v1/customers` e use o `customer.id` nas próximas cobranças, para não repetir os dados. Cada pedido continua sendo uma cobrança Pix nova. ## Checklist de implementação * [ ] Endpoint de webhook cadastrado no painel, em HTTPS, e `postbackUrl` em outra URL em cada cobrança * [ ] Cobrança Pix criada pelo servidor, nunca pelo navegador ou pelo celular da atendente com a chave secreta * [ ] `amount` em reais e igual à soma dos itens * [ ] Validade definida com `expirationInDays` ou `expirationInSeconds` * [ ] Mensagem com o `copyPaste` separado, e QR Code opcional a partir de `qrCodeBase64` * [ ] `id` da cobrança salvo junto do pedido * [ ] Pedido marcado como pago só com `status` `paid` confirmado na API * [ ] Idempotência persistente pelo `id` do evento * [ ] Rotina de expiração que consulta a cobrança antes de cancelar o pedido * [ ] Estorno implementado para pedidos cancelados depois do pagamento ## Como homologar Os cenários aplicáveis são CHG-04 (Pix gerado, com o copia e cola na resposta), CHG-05 (Pix pago e `charge.paid` recebido), CHG-06 (consulta), CHG-07 (estorno), CHG-08 (recebimento de webhook) e CHG-09 (reenvio de webhook de teste). Se vender produto físico, inclua CHG-10. Com a chave de teste, o Pix é confirmado sozinho: a cobrança nasce `pending`, com um QR Code fictício que não deve ser pago, e passa para `paid` cerca de 5 segundos depois, com `charge.paid` chegando com `livemode: false`. Não dá para simular a expiração no Modo Teste; para testar o tratamento de outros status, use o reenvio de webhook de teste, que dispara um evento novo e não altera a cobrança. Detalhes no [roteiro de homologação](/homologacao/roteiro). ## Veja também > [card] [Pix](/guias/cobrancas/pix) > > Validade, QR Code e copia e cola. > [card] [Sua primeira cobrança](/primeiros-passos/primeira-cobranca) > > Uma cobrança Pix completa. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos e formato do payload. > [card] [Clientes](/guias/clientes) > > Cadastro e reaproveitamento de clientes. # E-commerce de produtos físicos Source: https://docs.fastpaybrasil.com/casos-de-uso/e-commerce Checkout de loja virtual com Pix de validade curta, cartão parcelado, Apple Pay e 3D Secure, com entrega, estorno, disputas e recompra com cartão salvo. Uma loja virtual que vende produtos físicos precisa de um checkout que aceite as formas de pagamento que o cliente espera e mantenha o estoque alinhado com o pagamento. Também precisa avisar o sistema de pedidos quando o dinheiro entra e tratar o pós-venda: devolução, contestação e recompra. Esta página mostra como montar esse fluxo completo com a API da Finvia. > [!TIP] > > Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](/integrar-com-ia). Implementar este caso com um assistente de IA Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/casos-de-uso/e-commerce.md](https://docs.fastpaybrasil.com/casos-de-uso/e-commerce.md) * [https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md) * [https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) * [https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md) * [https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/pix.md](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar neste projeto o fluxo descrito na página "E-commerce de produtos físicos" ([https://docs.fastpaybrasil.com/casos-de-uso/e-commerce.md](https://docs.fastpaybrasil.com/casos-de-uso/e-commerce.md)). Resumo do caso: Checkout de loja virtual com Pix de validade curta, cartão parcelado, Apple Pay e 3D Secure, com entrega, estorno, disputas e recompra com cartão salvo. Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## O cenário A **Trilha Leve** é uma loja virtual de equipamentos de camping com sede em Curitiba. Ela fatura cerca de R\$ 430 mil por mês, com 1.800 pedidos e ticket médio de R\$ 240. Os pedidos saem por transportadora para todo o Brasil. O que a Trilha Leve precisa: * **Pix com validade curta**, para não segurar estoque de pedido que não vai ser pago. * **Cartão parcelado em até 6x**, porque barracas e mochilas passam de R\$ 600. * **Apple Pay** no checkout web, para clientes que compram pelo iPhone. * **3D Secure** no cartão digitado, conduzido pela Finvia, sem montar a autenticação do zero. * **Pedido atualizado sozinho** quando o pagamento é confirmado, estornado ou contestado. * **Recompra com um clique** para quem já comprou, com o cartão guardado no cofre da Finvia. ## O que a Finvia resolve > [!NOTE] > > **Para o negócio:** a mesma rota de cobrança (`POST /v1/charges`) atende Pix, cartão digitado, cartão salvo e Apple Pay. No cartão, a aprovação ou a recusa volta na própria resposta, então o checkout pode oferecer outra forma de pagamento na mesma tela. No Pix, o QR Code volta na resposta e a confirmação chega depois, por webhook (uma notificação que a Finvia envia ao sistema da loja). O estorno é feito por API. Quando uma venda é contestada (chargeback no cartão ou MED no Pix), a cobrança é bloqueada e a loja recebe um aviso. ## Arquitetura da solução | Necessidade | Recurso | Rota ou guia | | - | - | - | | Pagamento instantâneo com prazo curto | Cobrança Pix com `expirationInSeconds` | `POST /v1/charges` · [Pix](/guias/cobrancas/pix) | | Parcelamento | Cartão de crédito com `installments` (de `1` a `12`) | `POST /v1/charges` · [Cartão de crédito](/guias/cobrancas/cartao-de-credito) | | Autenticação do portador | 3DS gerenciado (`threeDSMode: "managed"`) | `POST /v1/charges` · [3DS gerenciado](/guias/3d-secure/gerenciado) | | Carteira digital | Apple Pay (objeto `wallet`) | `POST /v1/charges` · [Apple Pay](/guias/cobrancas/apple-pay) | | Entrega | `shippingAddress` e `trackingInfo` | `POST /v1/charges` | | Atualização do pedido | Webhooks cadastrados no painel e `postbackUrl` | [Webhooks de cobrança](/guias/webhooks/cobranca) | | Conferência de status | Consulta da cobrança | `GET /v1/charges/{id}` | | Devolução | Estorno total | `POST /v1/refunds` · [Estorno](/guias/estorno) | | Contestação | Bloqueio, pré-chargeback, chargeback e MED | [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) | | Recompra | Cliente, cofre de cartões e cobrança com `cardTokenId` | `POST /v1/customers`, `POST /v1/cards` · [Cartão salvo](/guias/cobrancas/cartao-salvo) | O desenho abaixo mostra o caminho de uma compra na Trilha Leve, do checkout ao pedido liberado, com a rota usada em cada passo. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB C(["Comprador
no site ou no iPhone"]):::comprador F["Checkout da Trilha Leve
chave pública pk_"]:::lojista S["Servidor da loja
chave secreta sk_"]:::lojista API["Finvia API"]:::finvia ADQ["Adquirente e bandeiras
cartão e Apple Pay"]:::externo PIX["Sistema Pix
banco do comprador"]:::externo EV[["Eventos charge.*
paid · refunded · blocked"]]:::evento AUT["Página 3DS da Finvia
authenticationUrl"]:::finvia W["Receptor de webhooks
endpoint e postbackUrl"]:::lojista P["Sistema de pedidos
e estoque"]:::lojista OK(["Pedido pago
vai para separação"]):::ok C -->|"1. escolhe Pix, cartão
ou Apple Pay"| F F -->|"2. envia o pedido"| S S ==>|"3. POST /v1/charges
pix ou credit_card
Apple Pay com wallet"| API API -.->|"4. 201 com o status
ou o QR Code"| S API -->|"5a. autoriza em até 6x"| ADQ API -->|"5b. Pix válido por 15 min"| PIX API -->|"6. publica o evento"| EV API -.->|"5c. se o banco pedir 3DS"| AUT EV -.->|"7. entrega nos dois canais"| W W -->|"8. confere com
GET /v1/charges/{id}"| P P ==>|"9. status paid"| OK classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` O 3DS só entra quando a política 3DS da conta pede. O Apple Pay usa a mesma rota, com o objeto `wallet`. Depois da criação, cada cobrança segue um destes caminhos. O desenho mostra o que o sistema de pedidos faz em cada um. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Pedido no checkout"]):::neutro Q{"Pix ou cartão?"}:::decisao PEN["pending
QR Code na tela
estoque reservado 15 min"]:::alerta R{"Resposta
da criação?"}:::decisao AUT["authentication_required
comprador na
authenticationUrl"]:::alerta AN["in_analysis
revisão do antifraude"]:::alerta FIM{"Resultado
final?"}:::decisao REC["refused ou failed
oferece outra forma"]:::erro EXP["Pix expirado
charge.updated failed
libera a reserva"]:::erro PAID["paid
pedido pago
vai para separação"]:::ok REF["refunded
devolvido, item
volta ao estoque"]:::neutro BLK["isBlocked: true
pedido em disputa"]:::alerta CB["chargeback
registra a perda"]:::erro INI --> Q Q -->|"Pix"| PEN Q -->|"cartão ou
Apple Pay"| R PEN ==>|"pagou · charge.paid"| PAID PEN --->|"15 min sem pagar"| EXP R ==>|"aprovado"| PAID R -->|"antifraude"| AN R -->|"banco pediu 3DS"| AUT R -->|"recusado"| REC AN -->|"análise termina"| FIM AUT -->|"verificação termina"| FIM FIM -->|"aprovado"| PAID FIM -->|"negado ou
não autorizado"| REC PAID -->|"devolução
POST /v1/refunds"| REF PAID -->|"contestação
charge.blocked"| BLK BLK -.->|"bloqueio liberado
consulte isBlocked"| PAID BLK -->|"alerta devolvido
charge.refunded"| REF BLK -->|"formalizado
charge.updated"| CB classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` O aviso de Pix expirado e o chargeback formalizado chegam só como `charge.updated` no `postbackUrl`. A liberação do bloqueio não gera aviso. ## Passo a passo **1. Prepare credenciais e webhooks** No painel (`https://app.finvia.com.br`), em **Configurações** > **Chave de API**, revele a chave secreta (`sk_`) e a chave pública (`pk_`). A secreta fica só no servidor. A pública vai para o navegador, onde o Apple Pay a usa. Se a chave for gerada por outro usuário, ele precisa ter o perfil **Owner** ou **Manager**: a chave age com o perfil de quem a gerou, e o perfil Desenvolvedor recebe `403` ao criar cobranças. Em **Configurações** > **Webhooks**, cadastre a URL que vai receber os eventos de cobrança, por exemplo `https://loja.exemplo.com.br/webhooks/finvia`. Envie também uma URL de postback em toda cobrança (`postbackUrl`). Além dos mesmos eventos do endpoint, ela recebe o evento legado `charge.updated`, que é o único aviso de Pix expirado e de recusa informada depois pela adquirente, e o único que traz o `status: "chargeback"` do chargeback formalizado. > [!TIP] > > **Para o desenvolvedor:** use URLs diferentes para o endpoint e para o `postbackUrl`, como nesta página (`/webhooks/finvia` e `/webhooks/finvia/postback`). Se a mesma URL estiver nos dois lugares, ela recebe cada evento duas vezes. **2. Crie a cobrança Pix com validade curta** O cliente escolhe Pix no checkout. A Trilha Leve cria a cobrança com validade de 15 minutos (`900` segundos, o mínimo aceito), reserva o estoque durante esse prazo e mostra o QR Code. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 239.8, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "phone": "+5511987654321", "document": { "type": "cpf", "id": "52998224725" }, "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInSeconds": 900 }, "items": [ { "title": "Saco de dormir", "type": "physical", "description": "Saco de dormir 5 graus, cor verde", "unit_price": 119.9, "quantity": 2 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "trackingInfo": { "trackingStatus": "awaiting_shipment" }, "metadata": { "pedido": "TL-10482" }, "postbackUrl": "https://loja.exemplo.com.br/webhooks/finvia/postback" }' ``` Como o item é `physical`, o `shippingAddress` é obrigatório. Sem ele, a API responde `400` com `Shipping info must be provided for merchants selling physical items.` e não cria a cobrança. `addressLine2` e `neighborhood` são opcionais: se o cliente não tem complemento, omita o campo. A resposta traz `status` `pending` e, em `paymentDetails`, o `copyPaste` (código copia e cola) e o `qrCodeBase64` (imagem pronta para a tag ``). Se `qrCodeBase64` vier `null`, mostre só o `copyPaste`. ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "pending", "paymentDetails": { "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo..." }, "reason": null } ``` Guarde o `id` junto do pedido `TL-10482`. É ele que liga o pedido aos webhooks. **3. Crie a cobrança no cartão parcelado com 3DS gerenciado** Para o cartão digitado, a Trilha Leve pede à Finvia que conduza a autenticação 3D Secure (3DS), a verificação do portador junto ao banco emissor. Com `threeDSMode: "managed"`, envie também o objeto `browser`, com os dados do navegador do comprador. Dentro dele, `userAgent` e `ipAddress` são obrigatórios. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 659.4, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "1111222233334444", "holderName": "JOAO SILVA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 6, "threeDSMode": "managed", "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } }, "items": [ { "title": "Barraca 4 pessoas", "type": "physical", "description": "Barraca iglu com sobreteto", "unit_price": 659.4, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "city": "São Paulo", "state": "SP", "country": "BRA" }, "metadata": { "pedido": "TL-10483" }, "postbackUrl": "https://loja.exemplo.com.br/webhooks/finvia/postback" }' ``` O 3DS só entra quando a política 3DS da conta pede (3DS obrigatório, ou valor igual ou acima do mínimo configurado). A resposta depende do caso: | Resposta | O que significa | O que a Trilha Leve faz | | - | - | - | | `paid` | Aprovada, com autenticação sem atrito ou sem 3DS | Confirma o pedido | | `refused` ou `failed` | Recusada; o motivo vem em `reason` | Mostra o motivo e oferece outra forma de pagamento | | `in_analysis` | Enviada para revisão manual do antifraude | Aguarda o webhook ou consulta a cobrança | | `authentication_required` | O banco pediu verificação ou desafio; a resposta traz `authenticationUrl` | Leva o comprador até a `authenticationUrl` | Com `authentication_required`, abra o endereço recebido em `authenticationUrl` em um modal, iframe ou nova aba. Use o valor exatamente como veio, sem montar nem alterar a URL. A página da Finvia conduz a verificação e o desafio do banco e conclui a cobrança. O resultado chega pelos webhooks (`charge.paid`, `charge.pending`, `charge.refused` ou `charge.failed`) e pode ser conferido em `GET /v1/charges/{id}`. A página não devolve o comprador à loja automaticamente, então mantenha o checkout aberto acompanhando o resultado. O passo a passo está em [3DS gerenciado](/guias/3d-secure/gerenciado). > [!WARNING] > > Se o comprador abandonar a autenticação, a cobrança continua em `authentication_required` e não gera webhook. Os dados do cartão ficam guardados por 15 minutos; depois disso, a cobrança não é mais processada e é preciso criar outra. Nunca trate uma cobrança em `authentication_required` como paga. **4. Ofereça Apple Pay no checkout web** A preparação é feita uma vez, com a chave secreta: registrar o domínio do checkout (`POST /v1/apple-pay/domains`), hospedar o arquivo de verificação em `/.well-known/apple-developer-merchantid-domain-association` e validar o domínio (`POST /v1/apple-pay/domains/{id}/validate`). Registrar o primeiro domínio ativa o Apple Pay na conta. Cada hostname (inclusive `www`) é um registro separado. No navegador, o evento `onvalidatemerchant` chama `POST /v1/apple-pay/validate-merchant` com a chave pública. Quando o cliente autoriza, o backend envia o `payment.token` **sem alterações** em `paymentMethod.wallet.token`. A moeda precisa ser `BRL` e `customer.document` é obrigatório, porque o token da Apple não traz CPF. Colete o CPF antes de abrir a folha de pagamento. ```json theme={null} { "amount": 189.9, "currency": "BRL", "customer": { "name": "Ana Lima", "email": "ana@email.com", "document": { "type": "cpf", "id": "52998224725" } }, "paymentMethod": { "type": "credit_card", "installments": 1, "wallet": { "type": "applepay", "token": { "paymentData": { "version": "EC_v1", "data": "4bh5q3l...base64...", "signature": "MIAGCSqGSIb3DQEHAqCAMIAC...", "header": { "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZI...", "publicKeyHash": "Ut4Wu3+Tc7n3Ld5gqkX5lL/...", "transactionId": "31323334353637383930" } }, "paymentMethod": { "displayName": "Visa 1234", "network": "Visa", "type": "credit" }, "transactionIdentifier": "b1f6f7d2c9a45e3b..." } } }, "items": [ { "title": "Lanterna de cabeça", "type": "physical", "description": "Lanterna recarregável 300 lúmens", "unit_price": 189.9, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "postbackUrl": "https://loja.exemplo.com.br/webhooks/finvia/postback" } ``` O 3D Secure não se aplica ao Apple Pay: a autenticação já vem no token. Configure `supportedNetworks` só com `visa` e `masterCard`, as redes suportadas hoje. No Modo Teste, a cobrança Apple Pay sai aprovada e não há como forçar uma recusa com o token da Apple. **5. Atualize o pedido pelos webhooks** O sistema de pedidos reage aos eventos de cobrança. Os eventos do envelope padrão (`id`, `event`, `livemode`, `data`) chegam aos endpoints do painel e também ao `postbackUrl`. Nesse envelope, as chaves do primeiro nível de `data` vêm em snake\_case. ```javascript theme={null} app.post('/webhooks/finvia', async (req, res) => { const { id, event, livemode, data } = req.body; // Idempotência persistente: o mesmo evento pode chegar mais de uma vez if (id && (await eventosProcessados.existe(id))) return res.status(200).send('OK'); res.status(200).send('OK'); // O mesmo endpoint recebe eventos de teste e de produção if (livemode === false && process.env.NODE_ENV === 'production') return; if (['charge.paid', 'charge.refunded', 'charge.blocked'].includes(event)) { // Webhooks não têm assinatura HMAC: confirme o estado real na API const cobranca = await finvia.get(`/v1/charges/${data.id}`); if (cobranca.isBlocked) await pedidos.marcarEmDisputa(data.id); else if (cobranca.status === 'paid') await pedidos.marcarComoPago(data.id); else if (cobranca.status === 'refunded') await pedidos.marcarComoEstornado(data.id); } if (id) await eventosProcessados.salvar(id); }); ``` | Evento ou situação | O que a Trilha Leve faz no pedido | | - | - | | Resposta de criação com `pending` (Pix) | Mostra o QR Code e reserva o estoque por 15 minutos | | `charge.paid` | Confirma com `GET /v1/charges/{id}`, marca como pago e libera para separação | | Resposta de criação com `refused` ou `failed` (cartão) | Mostra o motivo e oferece outra forma de pagamento | | `charge.refused` ou `charge.failed` | Só registra: a recusa síncrona já veio na resposta de criação | | `charge.refunded` | Marca como estornado e devolve o item ao estoque | | `charge.blocked` | Marca o pedido como "em disputa" | | `charge.updated` no `postbackUrl`, com `status` `failed` | Pix cancelado ou expirado, ou recusa informada depois pela adquirente: libera a reserva | > [!TIP] > > **Para o desenvolvedor:** os endpoints do painel não recebem aviso de expiração do Pix nem de recusa informada depois pela adquirente. Esses casos chegam só como `charge.updated` no `postbackUrl` (formato camelCase, sem `id` e sem `livemode`). Controle também o prazo de 15 minutos no seu sistema e, antes de liberar o estoque, consulte a cobrança com `GET /v1/charges/{id}` para ter certeza de que ela não foi paga no último segundo. **6. Estorne quando houver devolução** O cliente devolveu o saco de dormir. A Trilha Leve recebe o produto, confere e pede o estorno. A API faz só **estorno total**, de cobrança `paid` em Pix ou cartão, e cada cobrança aceita um estorno. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/refunds" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Devolução do pedido TL-10482 pelo cliente" }' ``` ```json theme={null} { "status": "refunded", "reason": null, "pspRefundRefId": "psp_refund_abc123xyz" } ``` A resposta vem com `status` `refunded`: a cobrança passa a `refunded` e o evento `charge.refunded` é enviado. No Pix, a devolução é enviada na hora para a conta de origem; peça o estorno em até 90 dias do pagamento, que é o prazo das regras do Pix. No cartão, o crédito aparece na fatura do cliente conforme o prazo do banco emissor. | Resposta | Causa | | - | - | | `422` "Já existe um reembolso para esta cobrança" | O estorno já foi pedido. Não reenvie | | `404` "Cobrança não encontrada" | A cobrança não existe ou não está `paid` (inclusive já estornada ou em chargeback) | **7. Trate bloqueios, chargeback e MED** Quando uma venda é contestada, a equipe Finvia bloqueia a cobrança. No cartão, a contestação é o chargeback, aberto pelo banco emissor. No Pix, é o MED (Mecanismo Especial de Devolução), o mecanismo do Pix para pedir a devolução de um pagamento. O bloqueio não muda o status: a cobrança continua `paid` e passa a ter `isBlocked: true`. | Aviso recebido | Canal | O que fazer | | - | - | - | | `charge.blocked` | Endpoints e `postbackUrl` | Marcar o pedido como em disputa e reunir as evidências (nota, comprovante de entrega, rastreio) | | `charge.pre_chargeback` | Endpoints e `postbackUrl` | Alerta de pré-chargeback: marcar como em disputa | | `charge.refunded` com `chargeback_alert_refunded: true` | Endpoints e `postbackUrl` | O valor já foi devolvido no alerta: tratar o pedido como estornado | | `charge.updated` com `status: "chargeback"` | Só `postbackUrl` | Chargeback formalizado: registrar a perda e confirmar em `GET /v1/charges/{id}` | | `charge.refunded` depois de um chargeback | Endpoints e `postbackUrl` | O valor foi revertido do saldo | A liberação do bloqueio não gera aviso. Para saber se ele continua, consulte `isBlocked` em `GET /v1/charges/{id}` ou liste as cobranças bloqueadas com `GET /v1/charges?status=blocked`. Não existe rota de API para enviar defesa: o alerta de chargeback ou MED chega por e-mail à conta, e as evidências da venda são enviadas em resposta a esse e-mail, dentro do prazo indicado nele. O fluxo completo está em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). **8. Ofereça recompra com cartão salvo** Para a recompra com um clique, a Trilha Leve cadastra o cliente e registra o cartão no cofre da Finvia na primeira compra em que o cliente autoriza guardar o cartão. ```bash theme={null} # 1. Cadastre o cliente (e-mail e CPF ou CNPJ são obrigatórios para registrar cartão) curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" }' # 2. Registre o cartão para esse cliente curl -X POST "https://api-global.fastpaybrasil.com/v1/cards" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "1111222233334444", "holderName": "JOAO SILVA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123" }' ``` O cartão nasce com `status` `active`, sem transação de teste. Na recompra, a cobrança usa o `id` do cartão como `cardTokenId` e **pede o CVV de novo** ao cliente. Sem o `cvv`, a API responde `400` `CVV is required when using cardTokenId`. ```json theme={null} { "amount": 89.9, "currency": "BRL", "customer": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" }, "paymentMethod": { "type": "credit_card", "cardTokenId": "2RhQgK4vN8pT1wZ6yB3mC7dF", "cvv": "123", "installments": 1 }, "items": [ { "title": "Cartucho de gás", "type": "physical", "description": "Cartucho 230 g para fogareiro", "unit_price": 89.9, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "postbackUrl": "https://loja.exemplo.com.br/webhooks/finvia/postback" } ``` Nos exemplos, `2RhQg9M7ZCg3X3nMb9W1kX8Q` é o cliente e `2RhQgK4vN8pT1wZ6yB3mC7dF` é o cartão. ## Regras e cuidados > [!WARNING] > > **Valor em reais.** `"amount": 239.8` é R\$ 239,80. Confira também se a soma de `unit_price` × `quantity` dos itens bate com o `amount`, para o pedido e a cobrança terem o mesmo total. > [!WARNING] > > **Cofre compartilhado entre teste e produção.** No Modo Teste, a cobrança com `cardTokenId` é simulada, mas o cadastro do cartão é real e o mesmo cartão funciona com a chave de produção. Uma chamada com a chave de produção cobra de verdade. * **Endereço de entrega.** Com algum item `physical`, envie `shippingAddress` com `postalCode`, `addressLine1` (logradouro e número), `city`, `state` e `country` em três letras (`BRA`). `addressLine2` e `neighborhood` são opcionais. * **Rastreio.** `trackingInfo` é enviado na criação da cobrança. A documentação não traz uma rota para atualizar o rastreio depois, então use `trackingStatus` `awaiting_shipment` na criação e acompanhe a entrega no seu sistema. * **Recusa no cartão.** A recusa volta na resposta de criação, com o motivo em `reason`. O `charge.refused` (ou `charge.failed`) também é enviado, mas a resposta síncrona é a fonte principal. * **Postback em toda cobrança.** Sem `postbackUrl`, a loja não recebe o aviso de Pix expirado nem o `charge.updated` com `status: "chargeback"`, que chegam só nesse canal. * **Sem `Idempotency-Key`.** Se a criação der timeout, não reenvie às cegas: um segundo `POST` cria outra cobrança, e no cartão isso é cobrança em dobro. Recupere o `id` pelo webhook `charge.created` ou pela listagem, filtrando pelo dia e pelo e-mail ou documento do cliente (`GET /v1/charges?createdAtStart=2026-03-10&createdAtEnd=2026-03-10&searchFor=maria@email.com`), e compare `metadata` e `amount` com o pedido. O procedimento está em [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia). * **CVV a cada compra.** A cobrança com cartão salvo exige o CVV do comprador sempre. Ela não serve para cobrança automática sem o cliente presente. ## Variações do caso > [accordion] E se a loja vender também produtos digitais, como vale-presente? > > Uma cobrança só com itens `"type": "digital"` não precisa de `shippingAddress`. Se o pedido misturar vale-presente e produto físico, basta um item `physical` para o endereço passar a ser obrigatório. O fluxo de liberação após `charge.paid` é o mesmo descrito em [Infoprodutos](/casos-de-uso/infoprodutos). > [accordion] E se a loja preferir fazer o 3DS por conta própria? > > Sem usar `threeDSMode: "managed"`, a loja pode autenticar antes da cobrança com o [SDK de segurança](/guias/3d-secure/sdk) ou com as [rotas de 3DS](/guias/3d-secure/via-api) e enviar o resultado no objeto `threeDS` da cobrança. Só `state: "success"` permite seguir quando o 3DS é exigido pela configuração da conta. > [accordion] E se o cliente quiser pagar em 12x? > > `installments` aceita de `1` a `12`. O valor de `amount` é o total da compra. A taxa de cada parcela é a configurada na sua conta na Finvia. > [accordion] E se a loja tiver lojas parceiras vendendo no mesmo site? > > Aí o dinheiro deixa de ser só da Trilha Leve, e o desenho muda para o modelo com subcontas e split. Veja [Marketplace e PSP](/casos-de-uso/marketplace-psp). ## Checklist de implementação * [ ] Chave secreta gerada por Owner ou Manager e guardada só no servidor * [ ] Chave pública configurada no front-end para o Apple Pay * [ ] Endpoint de webhook cadastrado no painel, em HTTPS * [ ] `postbackUrl` enviado em toda cobrança, em uma URL diferente da do endpoint * [ ] `amount` em reais e igual à soma dos itens * [ ] `shippingAddress` com os campos obrigatórios sempre que houver item `physical` * [ ] Pix com `expirationInSeconds` a partir de `900` e controle do prazo no sistema de pedidos * [ ] QR Code exibido a partir de `qrCodeBase64`, com `copyPaste` como alternativa * [ ] Tratamento de `paid`, `refused`, `failed`, `pending`, `in_analysis` e `authentication_required` na resposta de criação * [ ] Comprador levado à `authenticationUrl` sem alterar a URL, com o resultado acompanhado por webhook ou consulta * [ ] Idempotência persistente pelo `id` do evento, separação por `livemode` e confirmação com `GET /v1/charges/{id}` * [ ] Domínio do Apple Pay registrado e com `status` `verified`; CPF coletado antes da folha de pagamento * [ ] Estorno total implementado, sem reenvio quando a resposta for `422` de estorno já existente * [ ] Tratamento de `charge.blocked`, `charge.pre_chargeback` e do `charge.updated` com `chargeback` * [ ] Recompra pedindo o CVV a cada compra ## Como homologar | Funcionalidade | Cenários | | - | - | | Pix e cartão | CHG-01 (cartão à vista), CHG-02 (parcelado), CHG-03 (recusa com o cartão `4444333322221112`), CHG-04 e CHG-05 (Pix gerado e pago sozinho no Modo Teste) | | Consulta, estorno e webhooks | CHG-06, CHG-07, CHG-08 e CHG-09 | | Entrega | CHG-10 (item `physical` sem `shippingAddress` gera `400`; com o endereço, `201`) | | Apple Pay | AP-01 a AP-06 | | Cartão salvo | SUB-01 (cadastro real, sem cobrança) e SUB-02 (cobrança simulada com a chave de teste) | As regras de 3DS e de antifraude da conta continuam valendo no Modo Teste. Se a conta exige 3DS ou tem antifraude ligado, a recusa pode vir dessas etapas, com `reason` começando com `3ds_` ou `antifraud_denied`. Para o CHG-03, use uma conta sem 3DS obrigatório. O detalhe de cada cenário e a evidência esperada estão no [roteiro de homologação](/homologacao/roteiro). ## Veja também > [card] [Pix](/guias/cobrancas/pix) > > Validade, QR Code e confirmação do pagamento. > [card] [3DS gerenciado](/guias/3d-secure/gerenciado) > > Autenticação conduzida pela Finvia. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos, envelopes e o canal de postback. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > Como acompanhar e responder a uma disputa. # Educação e mensalidades Source: https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades Escolas e cursos livres com mensalidade: assinaturas por série ou curso, Pix avulso para matrícula e material, inadimplência pelas retentativas, cancelamento e Pix mensal para quem não usa cartão. Escolas, cursos de idiomas, escolas de música e academias de esportes cobram uma mensalidade fixa, todo mês, durante o ano letivo, e algumas cobranças pontuais: matrícula, material didático, uniforme, passeio. O desafio é cobrar a mensalidade sem que o responsável precise lembrar de pagar, acompanhar quem está em atraso e oferecer uma alternativa para famílias que não usam cartão. Esta página mostra como montar isso com a API da Finvia. > [!TIP] > > Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](/integrar-com-ia). Implementar este caso com um assistente de IA Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md](https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md) * [https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md) * [https://docs.fastpaybrasil.com/guias/assinaturas/planos.md](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md) * [https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) * [https://docs.fastpaybrasil.com/guias/clientes.md](https://docs.fastpaybrasil.com/guias/clientes.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/pix.md](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) * [https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) * [https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md) * [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar neste projeto o fluxo descrito na página "Educação e mensalidades" ([https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md](https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md)). Resumo do caso: Escolas e cursos livres com mensalidade: assinaturas por série ou curso, Pix avulso para matrícula e material, inadimplência pelas retentativas, cancelamento e Pix mensal para quem não usa cartão. Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## O cenário A **Escola Viva Idiomas** é uma rede de cursos de inglês e espanhol em Campinas, com 1.100 alunos ativos. A mensalidade varia por nível: | Curso | Mensalidade | | - | - | | Kids (6 a 10 anos) | R\$ 289,00 | | Teens (11 a 16 anos) | R\$ 329,00 | | Adultos | R\$ 359,00 | Além da mensalidade, há a **matrícula** (R\$ 150,00, uma vez por ano) e o **material didático** (R\$ 240,00 por semestre). Hoje, 70% das famílias pagam no cartão e 30% pagam por Pix todo mês. O que a escola precisa: * cobrar a mensalidade no cartão automaticamente, todo mês; * cobrar matrícula e material por Pix, de forma avulsa; * saber quem está com a mensalidade em atraso e por quê; * cancelar a mensalidade quando o aluno sai, respeitando o prazo de arrependimento; * gerar o Pix mensal para as famílias que não usam cartão. ## O que a Finvia resolve > [!NOTE] > > **Para o negócio:** cada curso vira um plano de assinatura com o valor da mensalidade. O responsável financeiro do aluno vira um cliente, com o cartão guardado no cofre da Finvia, e a assinatura cobra esse cartão a cada ciclo. Quando a cobrança é recusada, a Finvia tenta de novo nas rodadas seguintes e envia um webhook a cada falha, com o motivo. Matrícula, material e mensalidades de quem paga por Pix são cobranças Pix avulsas, com validade em dias, confirmadas por webhook. ## Arquitetura da solução | Necessidade | Recurso | Rota ou guia | | - | - | - | | Valor de cada curso | Plano de assinatura mensal | `POST /v1/subscription-plans` · [Planos](/guias/assinaturas/planos) | | Responsável financeiro | Cliente com e-mail e CPF | `POST /v1/customers` · [Clientes](/guias/clientes) | | Cartão do responsável | Cofre de cartões | `POST /v1/cards` · [Cofre de cartões](/guias/cofre-de-cartoes) | | Mensalidade automática | Assinatura | `POST /v1/subscriptions` · [Assinaturas](/guias/assinaturas/visao-geral) | | Matrícula e material | Cobrança Pix avulsa | `POST /v1/charges` · [Pix](/guias/cobrancas/pix) | | Inadimplência | `subscription.payment_failed` e `subscription.expired` | [Webhooks de assinatura](/guias/webhooks/assinatura) | | Histórico por aluno | Consulta e listagem de assinaturas | `GET /v1/subscriptions/{id}` e `GET /v1/subscriptions` | | Saída do aluno | Cancelamento | `POST /v1/subscriptions/{id}/cancel` · [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) | > [!WARNING] > > Assinaturas não têm modo de teste: com a chave de teste, as cobranças da assinatura acontecem de verdade. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). O desenho abaixo mostra como a Escola Viva cobra a matrícula por Pix e a mensalidade por assinatura no cartão. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB R(["Responsável
financeiro do aluno"]):::comprador S["Sistema da secretaria
chave secreta sk_"]:::lojista API["Finvia API"]:::finvia PIX["Sistema Pix
banco do responsável"]:::externo MOT["Renovação automática
6h, 12h e 18h"]:::finvia ADQ["Adquirente e bandeiras
cartão de crédito"]:::externo EV[["subscription.*
e charge.paid"]]:::evento W["Receptor de webhooks"]:::lojista FIN(["Financeiro da escola
baixa ou atraso"]):::ok S -->|"1. um plano por curso
/v1/subscription-plans"| API R -->|"2. faz a matrícula"| S S ==>|"3. Pix da matrícula
POST /v1/charges"| API S ==>|"4. cliente, cartão
e assinatura"| API API -->|"5. QR Code de 3 dias"| PIX API -->|"6. mensalidade
todo mês"| MOT MOT -->|"7. cobra o cartão"| ADQ API -->|"8. publica o evento"| EV EV -.->|"9. entrega"| W W ==>|"10. confere e registra"| FIN classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Todo mês, a mensalidade segue um dos dois caminhos abaixo, conforme a forma de pagamento da família. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Mensalidade do mês"]):::neutro Q{"Como a família
paga?"}:::decisao REN["Assinatura cobra
o cartão salvo"]:::finvia R{"Cobrança
aprovada?"}:::decisao OKC["active
subscription.renewed
baixa a mensalidade"]:::ok PF["active
subscription.payment_failed
avisa o responsável"]:::alerta EXP["expired
subscription.expired
oferecer o Pix mensal"]:::erro PX["Pix avulso do mês
POST /v1/charges
expirationInDays 10"]:::lojista P{"Pagou no
prazo?"}:::decisao OKP["paid
charge.paid e GET
baixa a mensalidade"]:::ok NV["Pix venceu
a escola gera
uma cobrança nova"]:::alerta INI --> Q Q -->|"cartão"| REN Q -->|"Pix"| PX REN --> R R ==>|"sim"| OKC R -->|"não"| PF PF -->|"nova rodada
6h · 12h · 18h"| REN PF -->|"limite de tentativas
do ciclo"| EXP PX --> P P ==>|"sim"| OKP P -->|"não"| NV NV -.-> PX classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` A assinatura também passa a `expired` quando o plano chega ao `endDate`, no fim do ano letivo. ## Passo a passo **1. Crie um plano por curso** Gere a chave de API com um usuário **Owner** ou **Manager**: os perfis Desenvolvedor e Financeiro recebem `403` `Acesso negado` nas rotas de planos e assinaturas. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "2v2TGGb4NHTQWCiMmnelz2WVOZP", "name": "Inglês Teens 2026", "price": 329, "currency": "BRL", "recurrenceType": "monthly", "endDate": "2026-12-31", "buyerMessage": "Bem-vindo à Escola Viva Idiomas!", "paymentMethods": ["credit_card"], "status": "active" }' ``` A resposta `201` traz só o `id` do plano; para ver o plano completo, use `GET /v1/subscription-plans/{id}`. O `endDate` encerra as assinaturas do plano no fim do ano letivo: quando o período seguinte começaria depois dessa data, a assinatura passa a `expired` e chega `subscription.expired`. Para o ano seguinte, a escola cria um plano novo, com o valor reajustado. > [!NOTE] > > Alterar o preço de um plano existente não muda as assinaturas já criadas. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Por isso, a escola trabalha com um plano por curso e por ano. **2. Cobre a matrícula por Pix** Na matrícula, o responsável paga R\$ 150,00 por Pix. A cobrança vale 3 dias. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 150, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321" }, "paymentMethod": { "type": "pix", "expirationInDays": 3 }, "items": [ { "title": "Matrícula 2026", "type": "digital", "description": "Matrícula do aluno Pedro Souza, Inglês Teens", "unit_price": 150, "quantity": 1 } ], "metadata": { "aluno": "EV-4410", "tipo": "matricula", "ano": "2026" }, "postbackUrl": "https://secretaria.escolaviva.exemplo.com.br/webhooks/finvia" }' ``` O sistema da secretaria mostra o QR Code (`qrCodeBase64`) ou envia o `copyPaste` por e-mail ou WhatsApp, e confirma a matrícula quando recebe `charge.paid` e consulta a cobrança com `GET /v1/charges/{id}`. > [!NOTE] > > Os itens usam `"type": "digital"` porque matrícula e mensalidade não têm entrega. Se a escola também vender material impresso com entrega, envie o material como item `physical`: com ele, `shippingAddress` passa a ser obrigatório, e sem o endereço a API responde `400`. **3. Cadastre o responsável e o cartão** O pagador é o responsável financeiro do aluno. Para registrar o cartão, ele precisa de e-mail e CPF (ou CNPJ). ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "name": "Maria Souza", "email": "maria@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" }' ``` ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/cards" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "1111222233334444", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "alias": "Cartão da mensalidade" }' ``` O cartão nasce `active`, sem cobrança de validação. Se o responsável tiver dois filhos matriculados, o mesmo cliente e o mesmo cartão servem para as duas assinaturas. Nos exemplos, `2RhQg9M7ZCg3X3nMb9W1kX8Q` é o cliente, `2RhQgK4vN8pT1wZ6yB3mC7dF` é o cartão, `2RhQg9M7ZCg3X3nMb9W2kY9R` é o plano e `2RhQg9M7ZCg3X3nMb9W3kZ0S` é a assinatura. **4. Crie a assinatura da mensalidade** ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "cardTokenId": "2RhQgK4vN8pT1wZ6yB3mC7dF", "metadata": { "aluno": "EV-4410", "turma": "TEENS-3B" } }' ``` Como o plano não tem trial, a primeira mensalidade é cobrada na criação da assinatura. Com `status` `active` na resposta, a mensalidade do primeiro mês está paga. Com `firstCharge.pending: true`, o pagamento está em análise: não crie outra assinatura e aguarde `subscription.activated` ou `subscription.payment_failed`. Com `pending_activation` e `firstCharge.success: false`, o cartão foi recusado. A assinatura fica parada: não cobra, não renova e não tem retentativa automática. Para tentar de novo, peça outro cartão ao responsável e crie uma **nova** assinatura (ela terá outro `id`), ou ofereça o Pix mensal (variação abaixo). Cancele a assinatura pendente com `POST /v1/subscriptions/{id}/cancel` para ela não ficar na listagem. O ciclo fica ancorado na data da contratação. No plano mensal, o dia de referência é mantido: uma matrícula em 31/01 renova em 28/02 (ou 29/02) e volta para 31/03. A renovação é feita por uma rotina que roda às 6h, 12h e 18h (horário de Brasília), depois do fim do período. **5. Acompanhe a inadimplência** Quando a cobrança de renovação é recusada, a Finvia tenta de novo nas rodadas seguintes (6h, 12h e 18h), até o limite de tentativas do ciclo descrito em [Ciclo de vida](/guias/assinaturas/ciclo-de-vida). Cada falha gera `subscription.payment_failed`, e a assinatura continua `active` durante as retentativas. ```javascript theme={null} // Trecho do switch (event) do seu receptor de webhooks switch (event) { case 'subscription.payment_failed': await financeiro.registrarAtraso(data.metadata.aluno, { motivo: data.failure_reason, // texto, ex.: "Cartão vencido" ciclo: data.charge.billing_cycle, }); await comunicacao.avisarResponsavel(data.customer.email, data.failure_reason); break; case 'subscription.expired': // Retentativas esgotadas ou fim do ano letivo (endDate do plano) await financeiro.marcarAssinaturaEncerrada(data.metadata.aluno); break; } ``` | Situação | Status da assinatura | Evento | Ação da escola | | - | - | - | - | | Mensalidade paga | `active` | `subscription.renewed` | Baixar a mensalidade do mês | | Tentativa recusada | `active` | `subscription.payment_failed` | Avisar o responsável e pedir atualização do cartão | | Limite de tentativas do ciclo atingido | `expired` | `subscription.expired` | Tratar como inadimplente e oferecer o Pix mensal | | Fim do plano (`endDate`) | `expired` | `subscription.expired` | Rematrícula no plano do ano seguinte | Para saber se o `expired` veio de inadimplência ou do fim do ano letivo, compare a data com o `endDate` do plano e veja se houve `subscription.payment_failed` no ciclo. Para a lista de alunos em cada situação, use a listagem de assinaturas com o filtro de status: ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions?status=expired&page=1&size=50" \ -u "$FINVIA_API_KEY:" ``` O filtro aceita `pending_activation`, `active`, `cancelled` e `expired`, e há também `customerId` e `search` (nome ou e-mail do cliente, ou nome do plano). **6. Troque o cartão de quem está em atraso** A assinatura não permite trocar o cartão. Quando o responsável manda um cartão novo, a escola registra o cartão, cancela a assinatura atual e cria uma nova com o `cardTokenId` novo. A nova assinatura começa um ciclo novo, com cobrança imediata da mensalidade. > [!WARNING] > > Se a assinatura que está sendo trocada tiver **até 7 dias**, o cancelamento entra como arrependimento e estorna todas as cobranças pagas dela. Em trocas logo depois da matrícula, confira a data de criação antes de cancelar. **7. Cancele quando o aluno sair** ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W3kZ0S/cancel" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "reason": "Transferência do aluno para outra cidade" }' ``` O resultado segue uma regra da plataforma, aplicada a todo cancelamento e contada em dias completos desde a criação da assinatura: | Quando | Resultado | | - | - | | Até 7 dias da criação da assinatura | `cancellationType: "regret"`, estorno automático de todas as cobranças pagas e acesso revogado imediatamente. Não há como cancelar nesse prazo sem estornar | | Depois de 7 dias | `cancellationType: "regular"`, sem estorno; as cobranças param imediatamente e `accessRevokedAt` indica até quando o período pago vale | No cancelamento regular, a escola decide até quando o aluno frequenta as aulas, com base em `accessRevokedAt`. Qualquer multa ou aviso prévio previsto no contrato escolar é uma cobrança à parte, feita pela escola. ## Regras e cuidados > [!WARNING] > > **Não cobre a mensalidade com cartão salvo em `POST /v1/charges`.** Essa rota exige o CVV do responsável a cada cobrança, então não serve para cobrança automática. A mensalidade recorrente é feita pela assinatura. * **Moeda.** Planos cobrados no cartão aceitam só `BRL`. * **Documento do responsável.** CPF (11 dígitos) ou CNPJ (14 dígitos), com e-mail. Passaporte ou RG contam como "sem documento", e o registro do cartão é recusado com `400`. * **Plano congelado.** Reajuste anual exige plano novo e assinatura nova. * **Recorrência mensal.** `monthly` segue o ciclo a partir da contratação. O intervalo `custom` conta dias corridos e desliza no calendário. * **`failure_reason` é texto.** Use para exibir e registrar. Decida o fluxo pelo evento e pelo status. * **Recusa não gera `charge.*`.** A falha de uma mensalidade é avisada só por `subscription.payment_failed`. Cada mensalidade paga gera também `charge.created` e `charge.paid`, com `subscription_id` e `billing_cycle` no `metadata`. * **Permissão da chave.** Chaves geradas por usuários Desenvolvedor ou Financeiro recebem `403` em todas as rotas de planos e assinaturas; Visualizador só acessa as consultas. * **Assinaturas sem split.** As cobranças recorrentes das assinaturas não recebem split. Se a rede tiver unidades como subcontas e quiser ficar com parte da mensalidade, isso não sai automaticamente; o split só vale para cobranças avulsas em `POST /v1/charges`. ## Variações do caso > [accordion] Pix mensal para quem não usa cartão > > As assinaturas cobram só no cartão. Para as famílias que pagam por Pix, o sistema da escola gera, todo mês, uma cobrança Pix avulsa alguns dias antes do vencimento: > > ```json theme={null} > { > "amount": 329, > "currency": "BRL", > "customer": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" }, > "paymentMethod": { "type": "pix", "expirationInDays": 10 }, > "items": [ > { "title": "Mensalidade abril 2026", "type": "digital", "description": "Inglês Teens, aluno Pedro Souza", "unit_price": 329, "quantity": 1 } > ], > "metadata": { "aluno": "EV-4410", "tipo": "mensalidade", "competencia": "2026-04" }, > "postbackUrl": "https://secretaria.escolaviva.exemplo.com.br/webhooks/finvia" > } > ``` > > A escola envia o copia e cola ao responsável e baixa a mensalidade quando recebe `charge.paid` e confirma na API. Nesse modelo, a régua de cobrança (lembretes, segunda via, atraso) é toda da escola: quando o Pix vence sem pagamento, o sistema gera uma cobrança nova. Guarde o `id` de cada cobrança junto da competência, porque a listagem de cobranças não busca por `metadata`. > [accordion] E o material didático do semestre? > > O material é uma cobrança avulsa, igual à matrícula. Para parcelar no cartão, use `credit_card` com `installments` (até `12`), com o responsável presente para informar o CVV, ou com o cartão salvo (`cardTokenId` mais CVV). > [accordion] E se a escola tiver várias unidades com CNPJ próprio? > > Cada unidade pode ser uma subconta no Connect da rede. As assinaturas e cobranças de cada unidade são criadas com a chave da subconta dela, e o dinheiro entra no saldo da unidade. Lembre que o cartão pertence ao merchant da chave que o registrou: um cartão registrado na unidade Centro não pode ser usado na unidade Cambuí. As mensalidades por assinatura não recebem split; a rede só consegue separar uma parte automaticamente nas cobranças avulsas, como matrícula e material. Os eventos das assinaturas de cada unidade vão para os endpoints da subconta e para um endpoint da conta master com a opção de incluir subcontas. O modelo de subcontas está em [ERP e software de gestão](/casos-de-uso/erp-software-de-gestao). > [accordion] E se a escola der desconto para irmãos? > > Crie planos com o valor já com desconto (por exemplo, "Inglês Teens 2026, segundo irmão") e use o plano certo na assinatura de cada aluno. A assinatura não aceita alteração de valor depois de criada. ## Checklist de implementação * [ ] Um plano por curso e por ano, em `BRL`, com `endDate` no fim do ano letivo * [ ] Responsável financeiro cadastrado com e-mail e CPF * [ ] Cartão registrado e com `status` `active` * [ ] Assinatura criada com `metadata` do aluno e da turma * [ ] Tratamento de `active`, `pending_activation` e `firstCharge.pending`, com nova assinatura para tentar de novo após recusa * [ ] Webhooks `subscription.*` com idempotência persistente * [ ] Régua de comunicação a cada `subscription.payment_failed` * [ ] Tratamento de `subscription.expired`, separando inadimplência de fim do ano letivo * [ ] Troca de cartão por cancelamento e nova assinatura, considerando a janela de 7 dias * [ ] Cobranças Pix avulsas para matrícula, material e mensalidade de quem não usa cartão * [ ] Baixa das cobranças Pix só com `status` `paid` confirmado na API * [ ] Homologação com cartão real de valor baixo e cancelamento no mesmo dia ## Como homologar | Funcionalidade | Cenários | | - | - | | Assinaturas e cartão salvo | SUB-01 a SUB-06 | | Pix avulso | CHG-04, CHG-05 (no Modo Teste, o Pix vira `paid` sozinho cerca de 5 segundos depois), CHG-06, CHG-08 e CHG-09 | | Estorno de cobrança avulsa | CHG-07 | Detalhes e evidências no [roteiro de homologação](/homologacao/roteiro). ## Veja também > [card] [Assinaturas](/guias/assinaturas/visao-geral) > > Planos, assinaturas e o fluxo cards-first. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Retentativas, expiração e cancelamento. > [card] [SaaS por assinatura](/casos-de-uso/saas-assinaturas) > > O mesmo modelo com trial e troca de plano. > [card] [Cobrança por mensagem](/casos-de-uso/cobranca-por-link) > > Como enviar o Pix por WhatsApp ou e-mail. # ERP e software de gestão Source: https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao Sistema de gestão que cobra em nome dos próprios clientes: cada cliente vira subconta, as cobranças usam a chave da subconta, a taxa do software vem por split e a conciliação usa metadata e webhooks. Um software de gestão (ERP) já guarda os contratos, as mensalidades, os vencimentos e os recebimentos dos clientes dele. O passo seguinte é cobrar por dentro do sistema: o inquilino paga o aluguel, o paciente paga a consulta, e o dinheiro cai direto na conta da imobiliária ou da clínica. Esta página mostra como montar isso com o Connect, incluindo a cobrança da taxa do software e o cadastro de muitos clientes de uma vez. > [!TIP] > > Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](/integrar-com-ia). Implementar este caso com um assistente de IA Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md](https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/saques.md](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md) * [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md) * [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md) * [https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar neste projeto o fluxo descrito na página "ERP e software de gestão" ([https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md](https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md)). Resumo do caso: Sistema de gestão que cobra em nome dos próprios clientes: cada cliente vira subconta, as cobranças usam a chave da subconta, a taxa do software vem por split e a conciliação usa metadata e webhooks. Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## O cenário A **Chave Certa Sistemas** desenvolve um ERP para imobiliárias, com sede em Belo Horizonte. São **180 imobiliárias** clientes, que administram juntas cerca de 22 mil contratos de locação. Todo mês, cada imobiliária cobra aluguel, condomínio e taxas dos inquilinos. Hoje, a cobrança acontece fora do ERP e a baixa é manual. A Chave Certa quer: * gerar a cobrança de cada aluguel dentro do ERP, por Pix ou cartão; * que o dinheiro entre direto na conta da **imobiliária**; * receber **1% do [valor bruto](/glossario)** de cada cobrança paga como taxa de uso da funcionalidade; * dar baixa automática no contrato quando o pagamento for confirmado; * cadastrar as 180 imobiliárias sem pedir que cada uma envie documentos por e-mail. ## O que a Finvia resolve > [!NOTE] > > **Para o negócio:** com o Connect, a Chave Certa vira a conta master (MerchantMaster) e cada imobiliária vira uma subconta (SubMerchant), com cadastro, análise de documentos e saldo próprios. O ERP cria as cobranças com a chave da subconta da imobiliária, então o dinheiro entra no saldo dela. O campo `split` separa a taxa da Chave Certa no momento da venda. O `metadata` leva o identificador do contrato, e os webhooks avisam o ERP quando dar baixa. A imobiliária saca o saldo por Pix para a chave CNPJ dela. ## Arquitetura da solução | Necessidade | Recurso | Rota ou guia | | - | - | - | | Habilitar o modelo | Módulo Connect | Contato com o time Finvia | | Cadastrar a imobiliária | Subconta | `POST /v1/submerchants` · [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) | | Documentos enviados pela própria imobiliária | Token de upload | `POST /v1/submerchants/{merchantId}/document/upload-token` e `POST /v1/document-uploads` · [Sócios e documentos](/guias/fast-connect/socios-e-documentos) | | Acompanhar o cadastro | Consulta e listagem de subcontas | `GET /v1/submerchants/{merchantId}` e `GET /v1/submerchants` | | Cobrar em nome da imobiliária | Chaves da subconta | `GET /v1/submerchants/{merchantId}/api-keys` | | Taxa do ERP | `split` para a conta master | `POST /v1/charges` · [Cálculo de split](/guias/fast-connect/calculo-split) | | Taxas de cada imobiliária | Consulta de taxas | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` · [Taxas](/guias/fast-connect/taxas) | | Baixa automática | `metadata`, webhook na conta master com eventos das subcontas e consulta | [Webhooks de cobrança](/guias/webhooks/cobranca) · `GET /v1/charges/{id}` | | Repasse à imobiliária | Saque da subconta | `POST /v1/submerchants/{merchantId}/payout-requests` · [Saques](/guias/fast-connect/saques) | O desenho abaixo mostra como o ERP da Chave Certa cadastra as imobiliárias, cobra o aluguel em nome delas e dá baixa no contrato. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB IM(["Imobiliária
cliente do ERP"]):::comprador ERP["ERP da Chave Certa
conta master, chaves
no cofre de segredos"]:::lojista API["Finvia API · Connect"]:::finvia PIX["Sistema Pix
inquilino paga no banco"]:::externo EV[["charge.paid
com data.merchant_id"]]:::evento W["Endpoint da conta master
include_submerchants"]:::lojista OK(["Contrato baixado
na competência"]):::ok IM -->|"1. dados já estão no ERP"| ERP ERP -->|"2. lote de subcontas
POST /v1/submerchants"| API IM -.->|"3. documentos com
token de upload"| API API -.->|"4. aviso de status
active"| ERP ERP -->|"5. GET .../api-keys"| API ERP ==>|"6. POST /v1/charges
chave da subconta
split e metadata"| API API -->|"7. Pix de 3 dias"| PIX API -->|"8. publica o evento"| EV EV -.->|"9. entrega"| W W ==>|"10. GET /v1/charges/{id}
com a chave da subconta"| OK classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` O segundo desenho detalha a conciliação de um aluguel pago por Pix e o saque da imobiliária. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant I as Inquilino end box rgb(243,245,248) Sua aplicação participant E as ERP participant W as Receptor de webhooks end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant B as Banco do inquilino end E->>F: POST /v1/charges · chave da imobiliária · metadata erpContrato e erpCompetencia F-->>E: 201 · pending · copyPaste Note over E: Guarda o id da cobrança com o contrato e a competência E-->>I: Pix do aluguel, válido por 3 dias I->>B: Paga no app do banco B->>F: Confirma o Pix F-)W: charge.paid · data.merchant_id da imobiliária W->>F: GET /v1/charges/{id} com a chave da subconta F-->>W: paid · metadata do contrato W->>E: Baixa o contrato 4471 na competência 2026-03 E->>F: POST /v1/submerchants/{merchantId}/payout-requests F-)W: payout.approved ou payout.rejected Note over E,F: Fechamento diário: GET /v1/charges?status=paid com a chave de cada subconta ``` ## Passo a passo **1. Cadastre as imobiliárias em massa** O ERP já tem razão social, CNPJ, endereço, responsável e conta bancária de cada imobiliária. Um processo em lote percorre a base e chama `POST /v1/submerchants` para cada uma, com a chave da conta master da Chave Certa. ```javascript theme={null} for (const imob of imobiliariasSemSubconta) { const resposta = await finvia.post('/v1/submerchants', { legalName: imob.razaoSocial, tradeName: imob.nomeFantasia, companyTaxId: imob.cnpj, // só dígitos, com dígito verificador válido website: imob.site, averageMonthlyRevenue: imob.faturamentoMedioMensal, averageOrderValue: imob.aluguelMedio, productType: 'digital', legalRepresentative: { fullName: imob.responsavel.nome, idNumber: imob.responsavel.cpf, idType: 'cpf', dateOfBirth: imob.responsavel.nascimento, // formato AAAA-MM-DD nationality: 'Brasileira', email: imob.responsavel.email, motherName: imob.responsavel.nomeDaMae, gender: imob.responsavel.genero, // "M" ou "F" phones: [{ type: 'mobile', number: imob.responsavel.celular }], }, contactEmail: imob.emailContato, productDescription: 'Cobrança de aluguel, condomínio e taxas de locação', address: { addressLine1: `${imob.endereco.logradouro}, ${imob.endereco.numero}`, // ex.: "Av. Paulista, 1000" addressLine2: imob.endereco.complemento || undefined, // opcional, ex.: "Sala 12" neighborhood: imob.endereco.bairro, // obrigatório quando country é BRA city: imob.endereco.cidade, state: imob.endereco.uf, // UF válida, ex.: "MG" country: 'BRA', // três letras postalCode: imob.endereco.cep, // CEP com 8 dígitos }, phones: [{ type: 'mobile', number: imob.telefone }], postbackUrl: 'https://erp.chavecerta.exemplo.com.br/webhooks/finvia/conta', canAccessDashboard: false, bankAccount: { bankCode: imob.banco.codigo, agencyCode: imob.banco.agencia, accountNumber: imob.banco.conta, accountDigit: imob.banco.digito, accountType: 'checking', bankName: imob.banco.nome, recipientName: imob.razaoSocial, recipientDocument: imob.cnpj, }, }); await imob.salvarSubconta(resposta.id, resposta.legalRepresentatives); } ``` > [!NOTE] > > O `productType` aceita `digital`, `physical` ou `both` e descreve o que a subconta vende. A cobrança de aluguel não tem entrega física. Com `canAccessDashboard: false`, a imobiliária não recebe acesso ao painel e o objeto `user` não é exigido. Com país `BRA`, a API confere o dígito verificador do CNPJ e do CPF do responsável, a UF e o CEP: corrija esses dados no ERP antes de rodar o lote, porque um erro de validação volta como `400` com a lista de campos em `message`. Processe o lote em ritmo controlado, registre a resposta de cada chamada e reprocesse só as que falharam. A API não tem `Idempotency-Key`: antes de reenviar uma criação que deu timeout, procure a subconta pelo CNPJ, só com dígitos, com `GET /v1/submerchants?companyTaxId=11222333000181`. Se o reenvio responder `409` `Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.`, a subconta já foi criada na primeira chamada. **2. Deixe a própria imobiliária enviar os documentos** Para dispensar o envio de documentos por e-mail, o ERP mostra uma tela de envio para a imobiliária. O backend da Chave Certa emite um token de upload e entrega esse token ao navegador: ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/document/upload-token" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{}' ``` ```json theme={null} { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 300 } ``` O navegador envia os arquivos direto para a Finvia, com o token no lugar da chave: ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/document-uploads" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -F "cnpj_card=@cartao-cnpj.pdf" \ -F "social_contract=@contrato-social.pdf" \ -F "responsible_document_front=@cnh-frente.jpg" \ -F "responsible_document_back=@cnh-verso.jpg" \ -F "selfie_with_document=@selfie.jpg" ``` O token vale 300 segundos (5 minutos) e é de uso único, então emita um novo a cada abertura da tela e envie todos os arquivos na mesma chamada. A subconta e o sócio vêm de dentro do token, nunca do corpo. Sem `legalRepresentativeId`, os documentos de pessoa ficam ligados ao representante legal. Para um sócio adicional, informe o `id` dele (retornado em `legalRepresentatives` na criação) ao emitir o token. Os erros do arquivo vêm no formato `{ "error": "", "message": "...", "details": { ... } }`. Trate pelo código HTTP e pelo campo `error`, não pelo texto: | Resposta | Significado | | - | - | | `201` | Documentos recebidos | | `400` `NO_FILE_SENT` | Nenhum arquivo no envio | | `400` `INVALID_DOCUMENT_NAME` | Nome de campo fora da lista de documentos | | `401` | Token ausente, inválido ou expirado | | `403` | Token já usado | | `413` `FILE_TOO_LARGE` | Arquivo acima de 50 MB | | `415` `UNSUPPORTED_FILE_TYPE` | Tipo não aceito (aceitos: PDF, JPG, PNG, GIF, BMP e WebP) | | `422` `DOCUMENT_NOT_EDITABLE` | A subconta já foi aprovada e o documento não pode mais ser alterado | **3. Acompanhe o credenciamento da base** O ERP recebe os avisos de mudança de status (`pre_approved`, `correcting`, `active`, `rejected`, `blocked`) no `postbackUrl` informado no cadastro e, de tempos em tempos, confere a base pela listagem. Para filtrar por mais de um status, repita o parâmetro: ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&status=pre_approved&page=1&size=50" \ -u "$FINVIA_API_KEY:" ``` O filtro `status` aceita `active`, `inactive`, `pending`, `pre_approved`, `correcting`, `rejected` e `blocked`. Não separe os valores por vírgula: `?status=pending,correcting` devolve a lista vazia. A lista vem da subconta mais recente para a mais antiga. Outros filtros úteis: `search` (razão social, nome fantasia, e-mail ou CNPJ), `createdFrom` e `createdTo` (`AAAA-MM-DD`) e `completeness` (`complete` para subcontas com conta bancária ativa, `incomplete` para as sem). Se usar `orderBy`, escreva o nome do campo em snake\_case, como `-created_at`. Quando vier `correcting`, mostre à imobiliária o texto de `rejectionReason`. A correção é feita no painel da Finvia, na gestão de subcontas, por isso a Chave Certa precisa ter um operador com acesso ao painel para cuidar desses casos. **4. Guarde as chaves de cada imobiliária ativa** Com a subconta `active`, o ERP busca as chaves e guarda a chave secreta em um cofre de segredos, associada à imobiliária. ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/api-keys" \ -u "$FINVIA_API_KEY:" ``` Antes da ativação, a resposta é `404` "API keys not found for this submerchant.". Nunca guarde as chaves das imobiliárias no mesmo campo de banco das configurações comuns: elas dão acesso às cobranças de cada cliente. **5. Calcule a taxa do ERP por cobrança** A Chave Certa quer 1% do valor bruto. Como o split incide sobre o [valor líquido](/glossario), o percentual precisa ser ajustado com as taxas da subconta, consultadas com a chave da conta master: ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/fees-info" \ -u "$FINVIA_API_KEY:" ``` O valor líquido é o valor da cobrança menos a taxa transacional da subconta (fixa mais percentual). Exemplo com taxas ilustrativas: aluguel de R\$ 2.500,00 por Pix, com taxa de 1,5% e sem taxa fixa. | Passo | Conta | Resultado | | - | - | - | | Valor líquido (L) | 2.500 × (1 − 0,015) − 0 | R\$ 2.462,50 | | Taxa desejada | 1% × R\$ 2.500,00 | R\$ 25,00 | | Split a informar (s) | 25,00 ÷ 2.462,50, arredondado para cima na quarta casa | 1,0153% | | Conferência | 1,0153% × 2.462,50 | R\$ 25,00 para a Chave Certa | Arredondar para cima evita que a taxa fique um centavo abaixo do alvo: com `1,0152%`, o valor seria R\$ 24,9993, exibido como R\$ 24,99. Faça o cálculo a cada cobrança, com a linha `tx_spread` certa para o método, a bandeira e a parcela (`percentages[parcelas - 1]` e `fixed`). A taxa de antecipação só reduz a base quando a imobiliária antecipa o recebível; nesse caso, a taxa do ERP é recalculada sobre o valor antecipado. Detalhes e código em [Cálculo de split](/guias/fast-connect/calculo-split). **6. Gere a cobrança com a chave da imobiliária** O ERP cria a cobrança do aluguel autenticando com a chave da subconta da imobiliária, leva o contrato no `metadata` e manda a taxa por `split` para a conta master da Chave Certa. O Pix vale 3 dias, para o inquilino pagar até o vencimento. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$CHAVE_SUBCONTA_IMOBILIARIA:" \ -H "Content-Type: application/json" \ -d '{ "amount": 2500, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321" }, "paymentMethod": { "type": "pix", "expirationInDays": 3 }, "items": [ { "title": "Aluguel março", "type": "digital", "description": "Contrato 4471, Rua das Acácias 120, apto 302", "unit_price": 2500, "quantity": 1 } ], "split": [ { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 1.0153 } ], "metadata": { "erpImobiliaria": "IMB-0093", "erpContrato": "4471", "erpCompetencia": "2026-03" }, "postbackUrl": "https://erp.chavecerta.exemplo.com.br/webhooks/finvia" }' ``` > [!NOTE] > > O percentual `1.0153` do exemplo foi calculado com a taxa ilustrativa de Pix do passo anterior. No cartão, use as linhas de taxa com `paymentMethod` `credit_card`, e o percentual muda. Nos exemplos desta página, `2vorkLm4Qp8TzR1sXc7Yb3NdWkE` é a subconta da imobiliária e `36OO3bcGjhPjjF3tzrqOGcmQuKo` é a conta master da Chave Certa. Guarde o `id` da cobrança junto do contrato e da competência no banco do ERP. **7. Concilie pelo metadata e pelos webhooks** A baixa no contrato acontece quando o ERP recebe `charge.paid` e confirma a cobrança na API. O `metadata` volta na consulta e no webhook, e diz qual contrato e qual competência baixar. Na consulta, as chaves de `metadata` voltam em camelCase; por isso o exemplo já envia `erpContrato` e `erpCompetencia` nesse formato. As cobranças pertencem às subcontas. Para receber os eventos de todas as imobiliárias em um lugar só, cadastre um endpoint na conta master com a opção de incluir subcontas: no painel, em **Configurações** > **Webhooks**, ou pela API, em `POST /v1/webhook-endpoints` com `include_submerchants: true`. O evento traz em `data.merchant_id` a subconta dona da cobrança. ```javascript theme={null} app.post('/webhooks/finvia', async (req, res) => { const { id, event, data } = req.body; if (id && (await eventos.jaProcessado(id))) return res.status(200).send('OK'); res.status(200).send('OK'); if (event === 'charge.paid') { const chave = await cofre.chaveDaSubconta(data.merchant_id); const cobranca = await finvia.get(`/v1/charges/${data.id}`, chave); if (cobranca.status === 'paid') { const { erpContrato, erpCompetencia } = cobranca.metadata; await contratos.darBaixa(erpContrato, erpCompetencia, cobranca.id); } } if (id) await eventos.marcarProcessado(id); }); ``` Envie também um `postbackUrl` em todas as cobranças, em uma URL diferente da do endpoint. Ele recebe os mesmos eventos e o `charge.updated` legado, que é o único aviso de Pix expirado e o único que traz o `status: "chargeback"` do chargeback formalizado (quando o valor é revertido do saldo, chega também `charge.refunded`). > [!TIP] > > **Para o desenvolvedor:** a listagem `GET /v1/charges` não busca por `metadata`. Por isso, guarde o `id` da cobrança no ERP no momento da criação: é ele que liga a cobrança ao contrato. Para um fechamento diário, liste com a chave de cada subconta as cobranças pagas do dia (`GET /v1/charges?status=paid&createdAtStart=2026-03-10&createdAtEnd=2026-03-10&page=1&size=50`) e compare com o que o ERP já baixou. As duas datas precisam vir juntas, pegam o dia inteiro em UTC, e a listagem vem sempre da mais recente para a mais antiga. **8. Repasse o saldo à imobiliária** A imobiliária saca o saldo por Pix para a chave CNPJ dela: a chave Pix do tipo CNPJ igual ao CNPJ do cadastro. O valor vai em reais, com mínimo de R\$ 1,00. O ERP pede o saque com a chave secreta da conta master e pode oferecer um botão de saque ou agendar saques. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/payout-requests" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 18450.75 }' ``` A resposta traz o `id` do saque. O saque nasce `pending`, sempre passa por aprovação da Finvia e termina `approved` (aprovado e enviado para pagamento) ou `rejected` (o valor volta ao saldo). Só pode haver um saque `pending` por vez. Peça a cada imobiliária que cadastre o CNPJ como chave Pix em uma conta bancária da empresa antes do primeiro saque: a API não confere se a chave existe, e sem ela o Pix não é concluído. Os avisos `payout.approved` e `payout.rejected` vão para os endpoints cadastrados na subconta e para o endpoint da conta master com a opção de incluir subcontas, o mesmo do passo anterior. Os valores (`amount`, `payoutFee`, `netAmount`) chegam como texto decimal, como `"18450.75000000"`: converta antes de usar. Confirme o status pela listagem `GET /v1/payout-requests?merchantId=2vorkLm4Qp8TzR1sXc7Yb3NdWkE` antes de dar baixa no repasse. Não existe saque no Modo Teste: com a chave de teste, a rota responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. ## Regras e cuidados > [!WARNING] > > **Chave errada, conta errada.** Uma cobrança criada com a chave da conta master entra no saldo da Chave Certa, e a imobiliária não recebe o valor. Confira, antes de cada chamada, se a chave usada é a da subconta dona do contrato. > [!WARNING] > > **O split incide sobre o líquido.** Informar `"percentage": 1` entrega menos de 1% do bruto. Calcule o percentual a cada cobrança com as taxas reais da subconta. * **Taxas copiadas na criação.** Cada subconta recebe uma cópia das taxas e configurações da conta master vigentes no momento da criação. Depois disso, elas são independentes: mudar as taxas da conta master não muda as das imobiliárias já cadastradas. * **Subconta só transaciona `active`.** Cobranças e chaves só existem depois da aprovação. * **Documentos depois da aprovação são bloqueados** (`422`). Faça a imobiliária revisar os arquivos antes de enviar. * **Taxas por subconta.** `fees-info` com a chave da conta master devolve as taxas da subconta pedida; com a chave da própria subconta, devolve sempre os dados dela e ignora o `id`. Lista `fees` vazia significa subconta sem taxas configuradas: as cobranças dela são recusadas com `422` `Fees not configured` até a Finvia configurar. Nesse caso, acione o suporte. * **Valores em reais** em cobranças, splits e saques. * **Sem busca por metadata.** Guarde o `id` da cobrança no ERP. * **Timeout na criação da cobrança.** Não reenvie de imediato: se a primeira chamada chegou, um novo `POST` cria uma segunda cobrança. Recupere o `id` pelo webhook `charge.created`, que traz o `metadata` como foi enviado, ou liste as cobranças do dia com a chave da subconta e `searchFor` com o documento ou o e-mail do inquilino. Só crie outra se nada for encontrado. O procedimento está em [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia). ## Variações do caso > [accordion] E se o ERP for para clínicas? > > O desenho é o mesmo: cada clínica é uma subconta, o paciente paga a consulta ou o procedimento pela cobrança criada com a chave da clínica, e o `metadata` leva o atendimento e o prontuário administrativo (nunca dados clínicos). Para planos de tratamento parcelados, use o cartão com `installments` até `12`. > [accordion] E se o ERP preferir cobrar uma mensalidade fixa da imobiliária? > > Aí a taxa da Chave Certa deixa de passar pelo split. A Chave Certa cobra a imobiliária como cliente dela, com uma assinatura na conta master, como em [SaaS por assinatura](/casos-de-uso/saas-assinaturas). As cobranças de aluguel continuam nas subcontas, sem `split`. > [accordion] E se a imobiliária repassar parte do aluguel ao proprietário do imóvel? > > Se o proprietário também tiver uma subconta no mesmo [grupo Connect](/glossario), a cobrança pode levar um segundo item no `split`, com a parte dele (relação subconta para subconta). O saque de subconta vai sempre para a chave Pix CNPJ do cadastro, então um proprietário pessoa física sem CNPJ não tem como sacar. Avalie com o time Finvia antes de desenhar esse fluxo. > [accordion] E se o inquilino quiser pagar no cartão? > > Troque `paymentMethod` por `credit_card` com os dados do cartão, coletados em uma página de pagamento do próprio ERP. A cobrança com cartão exige o CVV, então ela acontece com o inquilino presente. Para débito automático no cartão todo mês, use assinaturas na subconta da imobiliária. As cobranças recorrentes das assinaturas não recebem split, então a taxa da Chave Certa não sai automaticamente nesse caso. ## Checklist de implementação * [ ] Connect habilitado na conta do ERP * [ ] Lote de criação de subcontas com registro de resposta e reprocessamento só das falhas * [ ] Busca por CNPJ antes de recriar uma subconta após timeout * [ ] Tela de envio de documentos com token de upload emitido pelo backend * [ ] Tratamento dos avisos de status e operador com acesso ao painel para correções * [ ] Chaves das subcontas obtidas após `active` e guardadas em cofre de segredos * [ ] Cobranças criadas com a chave da subconta dona do contrato * [ ] Percentual do split calculado por cobrança com `fees-info` * [ ] `metadata` com contrato e competência, e `id` da cobrança salvo no ERP * [ ] Baixa automática só com `status` `paid` confirmado na API * [ ] Endpoint na conta master com `include_submerchants: true` para cobranças e saques das subcontas * [ ] Imobiliárias orientadas a cadastrar o CNPJ como chave Pix antes do primeiro saque * [ ] Fechamento diário comparando cobranças pagas com baixas no ERP ## Como homologar | Funcionalidade | Cenários | | - | - | | Subcontas | FC-01 a FC-08 (o FC-07, de saque, não roda com a chave de teste: combine a evidência com o suporte) | | Split | SPL-01 a SPL-06, com destaque para SPL-05 (valor da taxa conferido) | | Cobranças | CHG-04 a CHG-09 (Pix, consulta, estorno e webhooks) | Detalhes no [roteiro de homologação](/homologacao/roteiro). ## Veja também > [card] [Sócios e documentos](/guias/fast-connect/socios-e-documentos) > > Fluxo com token de upload e documentos por sócio. > [card] [Taxas da subconta](/guias/fast-connect/taxas) > > Como ler a resposta de `fees-info`. > [card] [Listar subcontas](/referencia/fast-connect/listar-subcontas) > > Filtros e paginação da base de subcontas. > [card] [Marketplace e PSP](/casos-de-uso/marketplace-psp) > > O mesmo modelo aplicado a um marketplace. # Infoprodutos e cursos online Source: https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos Venda de cursos e produtos digitais com Pix e cartão parcelado, liberação de acesso só depois do pagamento confirmado, reembolso, disputas e coprodução com split. Quem vende curso online, e-book, mentoria gravada ou comunidade paga entrega o produto no instante em que libera o acesso. Por isso, o ponto central da integração é liberar **só depois que o pagamento estiver confirmado**, e revogar quando houver reembolso ou contestação. Esta página mostra esse fluxo e, nas variações, como dividir a receita com coprodutores e afiliados. > [!TIP] > > Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](/integrar-com-ia). Implementar este caso com um assistente de IA Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md](https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md) * [https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/pix.md](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) * [https://docs.fastpaybrasil.com/guias/estorno.md](https://docs.fastpaybrasil.com/guias/estorno.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/split.md](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) * [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar neste projeto o fluxo descrito na página "Infoprodutos e cursos online" ([https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md](https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md)). Resumo do caso: Venda de cursos e produtos digitais com Pix e cartão parcelado, liberação de acesso só depois do pagamento confirmado, reembolso, disputas e coprodução com split. Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## O cenário A **Planilha Pro Educação** vende cursos de Excel e análise de dados para profissionais de escritório. O carro-chefe é o curso **Excel do Zero ao Dashboard**, por R\$ 497,00, em até 12x no cartão ou à vista no Pix. Em lançamentos, ela recebe até 1.200 pedidos em uma semana. O que a Planilha Pro precisa: * Pix com prazo de 1 hora, para o aluno pagar no app do banco sem pressa e sem deixar pedidos abertos por dias. * Cartão parcelado em até 12x. * Acesso à plataforma de aulas liberado só com pagamento confirmado. * Reembolso por API quando o aluno pede dentro do prazo de garantia da escola. * Em alguns cursos, divisão da receita com um professor coprodutor. ## O que a Finvia resolve > [!NOTE] > > **Para o negócio:** a cobrança é criada com itens do tipo `digital`, sem endereço de entrega. No cartão, o resultado volta na resposta. No Pix, a confirmação chega por webhook (`charge.paid`). A Planilha Pro libera o acesso quando recebe esse evento **e** confirma o status consultando a cobrança na API, porque os webhooks não têm assinatura criptográfica. O reembolso é um estorno total feito por API. Com o Connect, a receita de um curso pode ser dividida com coprodutores e afiliados no momento da venda. ## Arquitetura da solução | Necessidade | Recurso | Rota ou guia | | - | - | - | | Venda à vista instantânea | Cobrança Pix com `expirationInSeconds` | `POST /v1/charges` · [Pix](/guias/cobrancas/pix) | | Parcelamento | Cartão com `installments` até `12` | `POST /v1/charges` · [Cartão de crédito](/guias/cobrancas/cartao-de-credito) | | Produto digital | `items[].type` `digital` | `POST /v1/charges` | | Liberação de acesso | Webhook `charge.paid` e consulta da cobrança | [Webhooks de cobrança](/guias/webhooks/cobranca) · `GET /v1/charges/{id}` | | Reembolso | Estorno total | `POST /v1/refunds` · [Estorno](/guias/estorno) | | Contestação | Bloqueio por chargeback ou MED | [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) | | Coprodução e afiliados | Connect e `split` | [Split](/guias/fast-connect/split) | O desenho abaixo mostra a venda de um curso da Planilha Pro, do checkout à liberação do acesso. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB C(["Aluno"]):::comprador F["Checkout da Planilha Pro
itens digital, sem endereço"]:::lojista S["Servidor da escola
chave secreta sk_"]:::lojista API["Finvia API"]:::finvia ADQ["Adquirente e bandeiras
cartão em até 12x"]:::externo PIX["Sistema Pix
banco do aluno"]:::externo EV[["Eventos charge.*
paid · refunded · blocked"]]:::evento COP(["Coprodutor
subconta, opcional"]):::comprador W["Receptor de webhooks
endpoint e postbackUrl"]:::lojista PL["Plataforma de aulas"]:::lojista OK(["Acesso liberado"]):::ok C -->|"1. compra o curso
de R$ 497"| F F -->|"2. envia o pedido"| S S ==>|"3. POST /v1/charges
pix · credit_card"| API API -.->|"4. 201 com o status
ou o QR Code"| S API -->|"5a. autoriza o cartão"| ADQ API -->|"5b. Pix válido por 1 hora"| PIX API -->|"6. publica o evento"| EV API -.->|"split, se houver
coprodução"| COP EV -.->|"7. entrega"| W W -->|"8. confere com
GET /v1/charges/{id}"| PL PL ==>|"9. só com paid"| OK classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` A linha pontilhada da coprodução só existe quando a escola usa o Connect, como na variação do fim da página. A liberação e a revogação do acesso seguem as regras do desenho abaixo. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB EV[["charge.paid chega
ao receptor"]]:::evento CARD(["Cartão: a resposta
da criação veio paid"]):::neutro GET["GET /v1/charges/{id}
confere o status real"]:::lojista Q{"Status
na API?"}:::decisao ESP["Ainda não pago
não libera o acesso"]:::alerta LIB["paid
acesso liberado"]:::ok REF["refunded
acesso revogado"]:::neutro BLK["Em disputa
acesso suspenso"]:::alerta CB["chargeback
revoga e registra a perda"]:::erro EV --> GET GET --> Q Q ==>|"paid"| LIB Q -->|"outro status"| ESP CARD ==> LIB LIB -->|"reembolso na garantia
POST /v1/refunds"| REF LIB -->|"contestação
charge.blocked ou
charge.pre_chargeback"| BLK BLK -.->|"bloqueio liberado
consulte isBlocked"| LIB BLK -->|"alerta devolvido
charge.refunded"| REF BLK -->|"formalizado
charge.updated"| CB classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` ## Passo a passo **1. Monte os itens do pedido** Os cursos vão como itens `"type": "digital"`, e a cobrança não leva endereço de entrega. Se a Planilha Pro vender também uma apostila impressa, basta um item `physical` no pedido para o `shippingAddress` passar a ser obrigatório. Sem ele, a API responde `400` com `Shipping info must be provided for merchants selling physical items.`. **2. Crie a cobrança Pix** O aluno escolhe Pix. A cobrança vale 1 hora (`3600` segundos). ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 497, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInSeconds": 3600 }, "items": [ { "title": "Excel do Zero ao Dashboard", "type": "digital", "description": "Acesso ao curso por 12 meses", "unit_price": 497, "quantity": 1 } ], "metadata": { "pedido": "PP-20931", "curso": "excel-zero-dashboard" }, "postbackUrl": "https://planilhapro.exemplo.com.br/webhooks/finvia" }' ``` A resposta traz `status` `pending` e o QR Code em `paymentDetails`. Mostre a imagem de `qrCodeBase64` e um botão para copiar o `copyPaste`, que é o que o aluno usa quando está comprando pelo próprio celular. **3. Ou crie a cobrança no cartão parcelado** ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 497, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "1111222233334444", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 12 }, "items": [ { "title": "Excel do Zero ao Dashboard", "type": "digital", "description": "Acesso ao curso por 12 meses", "unit_price": 497, "quantity": 1 } ], "metadata": { "pedido": "PP-20932", "curso": "excel-zero-dashboard" }, "postbackUrl": "https://planilhapro.exemplo.com.br/webhooks/finvia" }' ``` Com `status` `paid`, o pagamento foi aprovado. Com `refused` ou `failed`, o motivo vem em `reason` e a página de checkout oferece o Pix ou outro cartão. Com `in_analysis`, a cobrança foi para revisão manual do antifraude: não libere o acesso e aguarde o desfecho. **4. Libere o acesso só com pagamento confirmado** A regra da Planilha Pro é: **nenhum acesso é liberado sem `status` `paid` confirmado pela API**. O webhook é o gatilho, e a consulta é a confirmação. ```javascript theme={null} app.post('/webhooks/finvia', async (req, res) => { const { id, event, data } = req.body; if (id && (await eventos.jaProcessado(id))) return res.status(200).send('OK'); res.status(200).send('OK'); if (event === 'charge.paid') { const cobranca = await finvia.get(`/v1/charges/${data.id}`); if (cobranca.status === 'paid') { await plataformaDeAulas.liberarAcesso(cobranca.metadata.pedido); } } if (event === 'charge.refunded') { const cobranca = await finvia.get(`/v1/charges/${data.id}`); if (cobranca.status === 'refunded') { await plataformaDeAulas.revogarAcesso(cobranca.metadata.pedido); } } if (id) await eventos.marcarProcessado(id); }); ``` > [!TIP] > > **Para o desenvolvedor:** no cartão, a resposta da criação já traz `paid`. Você pode liberar o acesso a partir dela, porque ela vem da chamada que o seu servidor fez à API. O que não deve liberar acesso sozinho é um POST recebido no endpoint de webhook sem confirmação: qualquer um que descubra a URL pode enviar um payload falso. O mesmo evento pode chegar mais de uma vez. Guarde os `id` de evento já processados em banco de dados ou cache persistente, que sobrevivem a uma reinicialização do servidor. **5. Reembolse dentro da garantia** A Planilha Pro oferece garantia de 7 dias. Quando o aluno pede o reembolso, o sistema verifica o prazo pela política da escola e pede o estorno total: ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/refunds" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido de reembolso dentro da garantia, pedido PP-20931" }' ``` | Resposta | O que fazer | | - | - | | `status` `refunded` | Revogar o acesso e confirmar ao aluno | | `422` "Já existe um reembolso para esta cobrança" | O estorno já foi pedido: não reenvie | | `404` "Cobrança não encontrada" | A cobrança não está `paid` (por exemplo, já estornada ou em chargeback). Consulte a cobrança antes de agir | A API faz só estorno total, e cada cobrança aceita um único estorno. Se a chamada der timeout, consulte a cobrança antes de reenviar: se ela já estiver `refunded`, não peça de novo. No Pix, a devolução é enviada na hora para a conta de origem do aluno; peça o estorno em até 90 dias do pagamento, que é o prazo das regras do Pix. No cartão, o crédito aparece na fatura conforme o prazo do banco emissor. **6. Acompanhe contestações** Se o aluno contestar a compra no banco (chargeback no cartão ou MED, o Mecanismo Especial de Devolução, no Pix), a equipe Finvia bloqueia a cobrança. Ela continua `paid`, passa a ter `isBlocked: true`, e o evento `charge.blocked` chega aos endpoints e ao `postbackUrl`. A Planilha Pro suspende o acesso enquanto a disputa corre e guarda as evidências da venda: registro de acesso às aulas, e-mail de compra, aceite dos termos. O alerta chega por e-mail à conta, e a Planilha Pro envia essas evidências em resposta a esse e-mail, dentro do prazo indicado nele. Não existe rota de API para defesa. | Aviso | O que a Planilha Pro faz | | - | - | | `charge.blocked` | Suspende o acesso | | `charge.pre_chargeback` | Alerta de pré-chargeback: suspende o acesso | | `charge.refunded` com `chargeback_alert_refunded: true` | O valor já foi devolvido no alerta: trata como reembolsado e revoga o acesso | | `charge.updated` com `status: "chargeback"` (só no `postbackUrl`) | Chargeback formalizado: revoga o acesso e registra a perda | A liberação do bloqueio não gera aviso: consulte `isBlocked` em `GET /v1/charges/{id}` para saber se o acesso pode voltar. O fluxo completo está em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ## Regras e cuidados > [!WARNING] > > **Não libere acesso a partir do webhook sem consultar a API.** Os webhooks não têm assinatura HMAC ([Webhooks](/guias/webhooks/visao-geral#regras-de-negócio)): confirme o status com `GET /v1/charges/{id}` antes de entregar o produto. > [!WARNING] > > **Valor em reais.** `"amount": 497` é R\$ 497,00. Enviar `49700` gera uma cobrança de R\$ 49.700,00. * **Pix mínimo de 15 minutos.** `expirationInSeconds` aceita a partir de `900`. Para prazos em dias, use `expirationInDays` (mínimo `1`). * **Sem endereço em produto digital.** `shippingAddress` é para produto físico. Em cobrança só com itens `digital`, não envie. * **Postback em toda cobrança.** O `charge.updated` com `status: "chargeback"` e os avisos de recusa informada depois pela adquirente chegam só pelo `postbackUrl`. * **Prazo de garantia é da sua política.** A API não impõe prazo máximo para pedir o estorno (no Pix, peça em até 90 dias do pagamento, pelas regras do Pix). Quem decide se o pedido está dentro da garantia é o seu sistema. > [!NOTE] > > Os formatos dos avisos são diferentes. No envelope padrão (`charge.paid`, `charge.refunded` e os demais), as chaves do primeiro nível de `data` vêm em snake\_case (`psp_ref_id`, `merchant_id`) e o `metadata` volta como foi enviado. O `charge.updated` e as respostas da API usam camelCase, inclusive nas chaves de `metadata`. Por isso, os exemplos usam chaves de `metadata` de uma palavra só (`pedido`, `curso`), que ficam iguais em todos os formatos. ## Variações do caso > [accordion] E se o curso tiver um professor coprodutor? > > A divisão automática exige o Connect. A Planilha Pro passa a ser a conta master e o coprodutor, uma subconta do mesmo grupo, com cadastro e KYC próprios. Na venda criada pela conta master, o `split` manda a parte do coprodutor para a subconta dele: > > ```json theme={null} > { > "amount": 497, > "currency": "BRL", > "customer": { "name": "Joao Silva", "email": "joao@email.com" }, > "paymentMethod": { "type": "pix", "expirationInSeconds": 3600 }, > "items": [ > { "title": "Power BI na Prática", "type": "digital", "description": "Curso em coprodução", "unit_price": 497, "quantity": 1 } > ], > "split": [ > { "merchantId": "2vorkDcXyvzifL63YX09S9VqcnI", "percentage": 40 } > ], > "postbackUrl": "https://planilhapro.exemplo.com.br/webhooks/finvia" > } > ``` > > O percentual incide sobre o **valor líquido**: o valor da venda menos a taxa transacional da Finvia. Se o acordo de coprodução já é sobre o líquido ("40% do que entrar"), informe `40`. Se o acordo é sobre o bruto, ajuste o percentual com a fórmula de [Cálculo de split](/guias/fast-connect/calculo-split). Se a Planilha Pro antecipar o recebível, o split é recalculado sobre o valor já descontada a taxa de antecipação. > > A parte do coprodutor é repassada quando o recebível da Planilha Pro é liquidado: no Pix, logo após a confirmação do pagamento; no cartão, parcela a parcela, em D+30, D+60 e assim por diante. Os eventos da cobrança vão só para a Planilha Pro, dona da venda; a subconta do coprodutor não recebe esses avisos. > [accordion] E se houver afiliados? > > Cada afiliado vira uma subconta no grupo da escola. Na venda indicada por um afiliado, a cobrança leva um segundo item no `split`, com a subconta do afiliado e o percentual combinado. A soma de todos os percentuais não pode passar de 100%, e o que sobra fica com quem originou a venda. Como o afiliado só recebe por subconta ativa, inclua o cadastro e o KYC dele no processo de entrada no programa. > [accordion] E se a escola quiser vender o curso por assinatura mensal? > > Use as assinaturas, que cobram o cartão automaticamente a cada ciclo. O desenho, com liberação e bloqueio de acesso por `subscription.*`, está em [SaaS por assinatura](/casos-de-uso/saas-assinaturas). As cobranças recorrentes das assinaturas não recebem split, então um curso em coprodução vendido por assinatura não divide a receita automaticamente. > [accordion] E se o aluno quiser comprar o segundo curso sem digitar o cartão de novo? > > Registre o cartão no cofre com `POST /v1/cards` (cliente com e-mail e CPF) e use `cardTokenId` na próxima compra. O CVV continua obrigatório a cada cobrança. Veja [Cartão salvo](/guias/cobrancas/cartao-salvo). ## Checklist de implementação * [ ] Itens enviados com `"type": "digital"` e sem `shippingAddress`; com item `physical`, endereço completo * [ ] Pix com validade definida (a partir de `900` segundos) * [ ] Cartão com `installments` até `12` * [ ] Liberação de acesso só com `status` `paid` confirmado em `GET /v1/charges/{id}` * [ ] Idempotência persistente pelo `id` do evento * [ ] Suspensão de acesso em `charge.blocked` e `charge.pre_chargeback`, e revogação em `charge.refunded` e no `charge.updated` com `chargeback` * [ ] Estorno com checagem prévia para não duplicar * [ ] `postbackUrl` em toda cobrança * [ ] Para coprodução e afiliados: Connect habilitado, subcontas ativas e percentuais somando até 100% ## Como homologar | Funcionalidade | Cenários | | - | - | | Pix e cartão | CHG-01, CHG-02, CHG-03, CHG-04 e CHG-05 | | Consulta, estorno e webhooks | CHG-06, CHG-07, CHG-08 e CHG-09 | | Coprodução e afiliados | FC-01 a FC-06 e SPL-01 a SPL-06 | No Modo Teste, o Pix passa sozinho para `paid` cerca de 5 segundos depois da criação (CHG-05), e o cartão `4444333322221112` gera a recusa do CHG-03. Use o reenvio de webhook de teste (CHG-09, `POST /v1/charges/{id}/resend-webhook`) para testar o tratamento de outros status: ele dispara um evento novo, com `id` novo, e não altera a cobrança. Como a consulta `GET /v1/charges/{id}` continua mostrando o status real, a liberação de acesso só acontece com um pagamento confirmado. Detalhes no [roteiro de homologação](/homologacao/roteiro). ## Veja também > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos, envelopes e retentativas. > [card] [Estorno](/guias/estorno) > > Estorno total e o que acontece com a cobrança. > [card] [Split](/guias/fast-connect/split) > > Como dividir uma venda entre contas do mesmo grupo. > [card] [Reenviar webhook de teste](/referencia/cobrancas/reenviar-webhook-teste) > > Simule eventos no sandbox. # Marketplace e PSP Source: https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp Plataforma com vários vendedores: subcontas com KYC, split com comissão calculada sobre o valor bruto, prazos de repasse, saques dos vendedores e avisos de conta e de saque. Um marketplace vende produtos de muitos lojistas em um só lugar. Cada venda pertence ao lojista, e a plataforma fica com uma comissão. Para isso funcionar, cada lojista precisa de uma conta própria, com cadastro e análise de documentos, e cada venda precisa separar a comissão da plataforma no momento do pagamento. Esta página mostra como montar esse modelo com o módulo Connect da Finvia e, no fim, como a mesma estrutura atende um PSP (provedor de serviços de pagamento) parceiro que cadastra seus lojistas como subcontas. > [!TIP] > > Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](/integrar-com-ia). Implementar este caso com um assistente de IA Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md) * [https://docs.fastpaybrasil.com/guias/webhooks/saque.md](https://docs.fastpaybrasil.com/guias/webhooks/saque.md) * [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar neste projeto o fluxo descrito na página "Marketplace e PSP" ([https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md)). Resumo do caso: Plataforma com vários vendedores: subcontas com KYC, split com comissão calculada sobre o valor bruto, prazos de repasse, saques dos vendedores e avisos de conta e de saque. Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## O cenário A **Feira Online** é um marketplace de produtos artesanais com **300 lojistas**: ceramistas, marceneiros, tecelãs, joalheiros. Cada lojista vende pelo site da Feira, recebe o dinheiro na própria conta e paga à plataforma uma comissão de **2% sobre o valor bruto** de cada venda. Os números da operação: | Indicador | Valor | | - | - | | Lojistas ativos | 300 | | Pedidos por mês | 6.500 | | Ticket médio | R\$ 100 | | Formas de pagamento | Pix e cartão em até 6x | | Comissão da plataforma | 2% sobre o valor bruto | ## O que a Finvia resolve > [!NOTE] > > **Para o negócio:** com o Connect, a Feira Online vira a conta master (MerchantMaster) e cada lojista ganha uma subconta (SubMerchant) vinculada a ela, com taxas, permissões e rastreabilidade próprias. Cada lojista passa pela análise de documentos (KYC, a verificação de identidade da empresa e dos sócios). Cada venda é criada na subconta do lojista, e o campo `split` define a parte da plataforma. O valor de cada participante é calculado na criação da cobrança e repassado a cada parcela, quando o recebível do lojista é [liquidado](/glossario): no cartão, a cada 30 dias por parcela (D+30, D+60...); no Pix, logo após a confirmação do pagamento. O lojista saca o próprio saldo por Pix para a chave CNPJ dele. ## Arquitetura da solução | Etapa | O que acontece | Rota | | - | - | - | | 1. Liberação | A Finvia habilita o módulo Connect na conta da Feira Online | Contato com o time Finvia | | 2. Cadastro do lojista | A Feira cria a subconta com dados da empresa, representante legal e conta bancária | `POST /v1/submerchants` | | 3. KYC | Envio de cartão CNPJ, contrato social, documento do responsável e selfie | `POST /v1/submerchants/{merchantId}/document` | | 4. Sócios adicionais | Documentos de cada sócio pelo fluxo com token | `POST /v1/submerchants/{merchantId}/document/upload-token` e `POST /v1/document-uploads` | | 5. Aprovação | A Feira acompanha o status até `active` | `GET /v1/submerchants/{merchantId}` e aviso de status de conta | | 6. Chaves do lojista | A Feira obtém as chaves da subconta ativa | `GET /v1/submerchants/{merchantId}/api-keys` | | 7. Taxas | A Feira consulta as taxas da subconta para calcular o split | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | | 8. Vendas com split | Cada venda é criada com a chave da subconta e a comissão em `split` | `POST /v1/charges` | | 9. Conferência | A Feira confere o split de cada venda | `GET /v1/charges/{id}` (campo `splits`) | | 10. Saque | O lojista saca o saldo via Pix para a chave CNPJ | `POST /v1/submerchants/{merchantId}/payout-requests` | | 11. Acompanhamento | Listagem de saques e avisos de saque | `GET /v1/payout-requests` e [Webhooks de saque](/guias/webhooks/saque) | O desenho abaixo mostra a ordem das chamadas, do cadastro do lojista à primeira venda com split. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Lojista e comprador participant L as Lojista participant C as Comprador end box rgb(243,245,248) Sua aplicação participant M as Feira Online end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant A as Adquirente end L->>M: Dados da empresa, sócios e documentos M->>F: POST /v1/submerchants F-->>M: 201 · id · subconta em pending M->>F: POST .../{merchantId}/document Note over F: Análise do cadastro em até 24 h, em média F-)M: pre_approved, depois active · URL de aviso de status M->>F: GET .../{merchantId}/api-keys F-->>M: secretKey da subconta M->>F: GET .../sub-accounts/{id}/fees-info C->>M: Compra um vaso de R$ 100 M->>F: POST /v1/charges com split F->>A: Autoriza o cartão F-->>M: 201 · paid F-)M: charge.paid · merchant_id ``` Depois da venda, o dinheiro segue o caminho abaixo. Os valores são os do exemplo desta página: venda de R\$ 100,00 no cartão em 2x, com taxa de 5% e R\$ 0,40 fixos. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB C(["Comprador paga R$ 100
no cartão em 2x"]):::comprador V["Venda na subconta
do Ateliê Barro Fino"]:::finvia AL["Saldo a liberar
do lojista · R$ 94,60
líquido da taxa"]:::alerta LQ["Liquidação da parcela
D+30 e D+60"]:::finvia FE["Saldo disponível
da Feira Online
R$ 1,00 por parcela"]:::ok LD["Saldo disponível
do lojista
R$ 46,30 por parcela"]:::ok SQ["Saque pending
valor reservado"]:::alerta AP{"Finvia
aprova?"}:::decisao BC["Conta do Ateliê
Pix na chave CNPJ
recebe netAmount"]:::externo RJ["rejected
valor volta ao saldo"]:::erro C ==>|"1. POST /v1/charges
com split"| V V -->|"2. fica a liberar"| AL AL -->|"3. cada parcela
a cada 30 dias"| LQ V -.->|"no Pix: no mesmo dia,
após a confirmação"| LQ LQ -->|"4. 2,1142% do líquido"| FE LQ -->|"4. o restante"| LD LD -->|"5. POST .../payout-requests
chave da conta master"| SQ SQ --> AP AP ==>|"approved
payout.approved"| BC AP -->|"payout.rejected"| RJ classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` No Pix, o repasse acontece no mesmo dia, logo após a confirmação do pagamento. O saque desconta a `payoutFee`, e o lojista recebe o `netAmount`. ## Regras de credenciamento do Connect Antes de cadastrar o primeiro lojista, conheça as regras que a Finvia aplica a toda conta master com Connect. As principais: | Regra | O que significa | | - | - | | Split obrigatório para PSP | Toda transação de PSP divide o valor entre a subconta e a conta master. A conta master não pode ficar com 100% da venda | | Pré-validação pela plataforma | A conta master confere os dados e documentos do lojista antes de enviar o cadastro | | 3DS para perfil de alto risco | Lojistas classificados como de alto risco precisam usar 3D Secure no cartão | | Estorno só pela API | O estorno é pedido por `POST /v1/refunds` | | Análise em até 24 horas | Tempo médio de análise do cadastro. É mais rápido quando não há divergência documental | | MCCs vedados | Alguns ramos de atividade não podem ser credenciados como subconta | O texto completo, com a lista de MCCs vedados, está em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). ## Passo a passo **1. Peça a liberação do Connect** O módulo é habilitado pela Finvia na conta da plataforma. Sem ele, as rotas do Connect respondem `403` `Fast Connect not enabled.`. Na criação, cada subconta recebe uma **cópia** das taxas e configurações da conta master vigentes naquele momento. Depois disso, as taxas da subconta são independentes: alterar as taxas da conta master não muda as das subcontas já criadas. Por isso, alinhe com o time Finvia as taxas da conta master antes de cadastrar o primeiro lojista. **2. Crie a subconta do lojista** A Feira Online cadastra o Ateliê Barro Fino, uma ceramista de São Paulo (SP), com a chave secreta da conta master. Todos os campos abaixo são obrigatórios, exceto `legalRepresentative.idType`, `address.addressLine2`, `softDescriptor` (texto da fatura do cartão, até 40 caracteres) e `postbackUrl`. Sócios adicionais, quando houver, vão no array opcional `additionalRepresentatives`. Com `canAccessDashboard: true`, o objeto `user` passa a ser obrigatório. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "legalName": "Atelie Barro Fino Ceramica Ltda", "tradeName": "Ateliê Barro Fino", "companyTaxId": "11222333000181", "website": "https://feiraonline.exemplo.com.br/barro-fino", "averageMonthlyRevenue": 8000, "averageOrderValue": 120, "productType": "physical", "legalRepresentative": { "fullName": "Ana Lima", "idNumber": "52998224725", "idType": "cpf", "dateOfBirth": "1986-04-12", "nationality": "Brasileira", "email": "ana@email.com", "motherName": "Maria Lima", "gender": "F", "phones": [{ "type": "mobile", "number": "+5511987654321" }] }, "contactEmail": "contato@barrofino.exemplo.com.br", "productDescription": "Peças de cerâmica artesanal: vasos, pratos e canecas", "softDescriptor": "BARROFINO", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [{ "type": "mobile", "number": "+5511987654321" }], "postbackUrl": "https://feiraonline.exemplo.com.br/webhooks/finvia/conta", "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana@email.com", "phone": "+5511987654321" }, "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "Atelie Barro Fino Ceramica Ltda", "recipientDocument": "11222333000181" } }' ``` ```json theme={null} { "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE", "legalRepresentatives": [ { "id": "2vorkEaaaBbbCccDddEeeFffGgg", "fullName": "Ana Lima", "isPrimary": true } ] } ``` A resposta `201` traz só o `id` da subconta e os representantes, com o representante legal primeiro. Para ver o cadastro completo, use `GET /v1/submerchants/{merchantId}`. A subconta nasce em análise. | Campo | Regra | | - | - | | `address.country` | Três letras (ISO 3166-1 alfa-3), como `BRA`. `BR` é recusado com `400` | | `companyTaxId` | Com país `BRA`, CPF ou CNPJ com dígito verificador válido. O CNPJ `11222333000181` desta página é fictício e tem dígitos válidos | | `address.state`, `address.postalCode`, `address.neighborhood` | Com país `BRA`: UF válida, CEP de 8 dígitos e bairro obrigatório | | `address.addressLine1` | Logradouro e número, separados por vírgula (`Av. Paulista, 1000`). O número é extraído desse formato no credenciamento; sem ele, pode seguir como "S/N" | | `address.addressLine2` | Complemento opcional, como `Sala 12` | | `legalRepresentative.idNumber` | CPF válido quando `issuingCountry` é `BRA` ou não é enviado. O CPF `52998224725` desta página é fictício e tem dígitos válidos | | `user.phone` | Formato internacional E.164, como `+5511987654321` | | Erro | Causa | | - | - | | `400` com `message` em lista | Campo inválido ou faltando, por exemplo `address.country must be a valid ISO31661 Alpha3 code` | | `400` `Email already registered` | O e-mail de `user` já tem acesso ao painel | | `409` `Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.` | O CNPJ já existe entre as subcontas da Feira (ou é o da própria conta master) | O `postbackUrl` do cadastro é a URL que recebe os avisos de mudança de status da subconta. Ele fica salvo nas configurações da subconta. Se você não enviar, a subconta usa a URL da conta master, se houver uma. Para trocar a URL depois, fale com o suporte. **3. Envie os documentos do KYC** A rota de documentos recebe `multipart/form-data`, com o nome de cada campo igual ao tipo de documento. Formatos aceitos: PDF, JPG, PNG, GIF, BMP ou WebP, até 50 MB por arquivo. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/document" \ -u "$FINVIA_API_KEY:" \ -F "cnpj_card=@cartao-cnpj.pdf" \ -F "social_contract=@contrato-social.pdf" \ -F "responsible_document_front=@rg-frente.jpg" \ -F "responsible_document_back=@rg-verso.jpg" \ -F "selfie_with_document=@selfie.jpg" ``` Os documentos de pessoa enviados por essa rota ficam ligados ao **representante legal**. Tipo de arquivo inválido, arquivo acima de 50 MB ou nome de campo fora da lista geram `400`. Depois que a subconta é aprovada, novos envios são recusados com `422`. > [!TIP] > > **Para o desenvolvedor:** se a empresa tem mais de um sócio, envie `additionalRepresentatives` na criação e use o fluxo com token para os documentos de cada sócio. Chame `POST /v1/submerchants/{merchantId}/document/upload-token` com o `legalRepresentativeId` do sócio e, em seguida, `POST /v1/document-uploads` com `Authorization: Bearer` e o token recebido. O token vale 300 segundos e é de uso único. Ele também permite que o próprio lojista envie os arquivos pelo navegador, sem expor a chave da plataforma. Detalhes em [Sócios e documentos](/guias/fast-connect/socios-e-documentos). **4. Acompanhe o credenciamento** O caminho comum é `pending` → `pre_approved` → `active`. A subconta só transaciona quando está `active`. | Status | Gera aviso? | Significado | | - | - | - | | `pending` | Não | Cadastro recebido, em análise. Também é o status depois do reenvio de uma correção | | `correcting` | Sim | A Finvia pediu correção de dados ou documentos; o motivo vem em `rejectionReason` | | `pre_approved` | Sim | Documentos conferidos; a subconta está sendo credenciada nas adquirentes e aguarda a aprovação final | | `active` | Sim | Aprovada e apta a transacionar. Também é enviado no desbloqueio | | `rejected` | Sim | Reprovada; o motivo vem em `rejectionReason` | | `blocked` | Sim | Bloqueada | | `inactive` | Não | Inativada | O aviso vai para o `postbackUrl` do cadastro, sem envelope e em camelCase. Ele não vai aos endpoints de webhook nem ao `postbackUrl` das cobranças. ```json theme={null} { "merchantId": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE", "status": "correcting", "date": "2026-01-13T12:39:48Z", "rejectionReason": "Documento de identidade ilegível. Reenvie o RG ou CNH com qualidade adequada." } ``` Responda com status 2xx em até 10 segundos; qualquer outra resposta conta como falha. O campo `date` é a data de referência do status (no `active`, a data de aprovação, que se mantém num desbloqueio), e não o momento exato do aviso. Trate o aviso como atualização de estado: grave o status e confirme com `GET /v1/submerchants/{merchantId}`. A correção de uma subconta em `correcting` é feita no painel, na gestão de subcontas. **5. Obtenha as chaves da subconta** Com a subconta `active`, a Feira busca as chaves dela e guarda no cofre de segredos, associadas ao lojista. ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/api-keys" \ -u "$FINVIA_API_KEY:" ``` ```json theme={null} { "publicKey": "pk_2vorkLm4Qp8TzR1sXc7Yb3NdWkE", "secretKey": "sk_2vorkLm4Qp8TzR1sXc7Yb3NdWkE" } ``` Enquanto a subconta não está ativa, a rota responde `404` "API keys not found for this submerchant.". Em modo de teste, as chaves têm prefixo `sk_test_` e `pk_test_`. A chave secreta e a pública formam um par: se uma for trocada, a outra também muda. **6. Calcule o percentual do split** Por padrão, a Finvia aplica o split sobre o [valor líquido](/glossario): o valor da venda menos a taxa transacional (fixa mais percentual). A Feira quer 2% do [valor bruto](/glossario). Se informar `"percentage": 2`, recebe menos do que deveria. O percentual precisa ser ajustado. Exemplo com taxas ilustrativas: venda de R\$ 100,00 no cartão em 2x, com taxa transacional de 5% e taxa fixa de R\$ 0,40. | Passo | Conta | Resultado | | - | - | - | | Valor líquido (L) | 100 × (1 − 0,05) − 0,40 | R\$ 94,60 | | Comissão desejada | 2% × R\$ 100,00 | R\$ 2,00 | | Split a informar (s) | 2,00 ÷ 94,60, arredondado para cima na quarta casa | **2,1142%** | | Conferência | 2,1142% × 94,60 | R\$ 2,00 para a Feira e R\$ 92,60 para o lojista | A fórmula geral é `L = V × (1 − f) − c` e `s = (p × V) ÷ L`. Nela, `V` é o valor bruto, `f` o percentual da taxa transacional, `c` a taxa fixa e `p` a comissão sobre o bruto. Arredondar `s` para cima na quarta casa evita que a comissão fique um centavo abaixo do alvo. As taxas vêm da própria subconta. Consulte com a chave da conta master: ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/fees-info" \ -u "$FINVIA_API_KEY:" ``` A resposta traz `fees` como uma lista plana. Cada linha tem `feeType` (`tx_spread` ou `anticipation`), `paymentMethod`, `currencyCode`, `brand` e `definition` (`fixed` e `percentages`). Para chegar à taxa transacional de uma venda em `n` parcelas, filtre as linhas `tx_spread` pelo método e pela moeda, use a linha da bandeira do cartão (ou a linha `brand: null`, se não houver uma da bandeira) e leia `percentages[n-1]` como `f` e `fixed` como `c`. > [!WARNING] > > **Antecipação muda a base.** A taxa de antecipação (`anticipation`) só entra na conta quando o lojista antecipa o recebível. Nesse caso, o split é recalculado sobre o valor já descontada a taxa de antecipação, e a Feira recebe proporcionalmente menos. A taxa de antecipação é mensal (só `percentages[0]` é usado), multiplicada pelo número de meses até o vencimento de cada parcela, com mínimo de 1 mês. Se `fees` vier vazio, ou sem linha para o método e a moeda da venda, a subconta está sem taxas configuradas e as cobranças dessa combinação são recusadas com `422` `Fees not configured`. Nesse caso, acione o suporte da Finvia. O detalhe, com o código de cálculo, está em [Cálculo de split](/guias/fast-connect/calculo-split). **7. Crie a venda na subconta, com split para a plataforma** A cobrança é autenticada com a **chave secreta da subconta do lojista**. É isso que vincula a venda ao lojista. O `merchantId` do split é o ID da conta master da Feira. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$CHAVE_SUBCONTA_BARRO_FINO:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" } }, "paymentMethod": { "type": "credit_card", "number": "1111222233334444", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 2 }, "items": [ { "title": "Vaso de cerâmica", "type": "physical", "description": "Peça artesanal, 30 cm", "unit_price": 100, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "split": [ { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 2.1142 } ], "metadata": { "pedidoFeira": "FO-88120", "lojista": "barro-fino" }, "postbackUrl": "https://feiraonline.exemplo.com.br/webhooks/finvia/postback" }' ``` Os 97,8858% restantes do líquido ficam com o lojista, que originou a venda. No exemplo, `36OO3bcGjhPjjF3tzrqOGcmQuKo` é a conta master da Feira e `2vorkLm4Qp8TzR1sXc7Yb3NdWkE` é a subconta do Ateliê. O `split` enviado na requisição vale só para essa venda e prevalece sobre a regra padrão da conta. Sem `split` na requisição, a API aplica a regra padrão da subconta para aquele método e moeda ou, se ela não tiver uma, a regra padrão definida pela conta master. Como a venda pertence à subconta, os eventos dela vão para os endpoints cadastrados na subconta, para os endpoints da conta master marcados para receber eventos das subcontas e para o `postbackUrl` da cobrança. O payload traz o `merchant_id` da subconta, e assim a Feira identifica o lojista. **8. Confira o split da venda** O campo `splits` aparece só na consulta individual da cobrança. Ele não vem na resposta de criação nem na listagem. ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI" \ -u "$CHAVE_SUBCONTA_BARRO_FINO:" ``` ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "paid", "amount": 100, "splits": [ { "id": "2vorkSp1tQx7RmB4nZc9WdLk3Hv", "destinyMerchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "destinyMerchantName": "Feira Online", "splitPercentage": "2.11420000", "splitAmount": 2, "referenceAmount": "net" } ] } ``` | Campo | O que traz | | - | - | | `destinyMerchantId` | Conta que recebe a parte (o `merchantId` enviado em `split`) | | `destinyMerchantName` | Nome fantasia da conta que recebe | | `splitPercentage` | Percentual, como texto decimal. Converta para número antes de comparar | | `splitAmount` | Valor exibido para quem recebe, em reais, truncado em 2 casas | | `referenceAmount` | Base de cálculo: `net` (valor líquido, o padrão) ou `gross` (valor bruto) | O `splitAmount` muda de significado ao longo da vida da venda. Enquanto houver parcelas a liquidar e nenhuma antecipação, ele mostra uma simulação: o valor que a Feira teria se o lojista antecipasse, já descontada a taxa de antecipação estimada, e por isso fica abaixo de R\$ 2,00. Depois que as parcelas liquidam sem antecipação, ele mostra o repasse efetivo, o percentual sobre o líquido (R\$ 2,00 no exemplo). Depois de uma antecipação, mostra o valor recalculado sobre o valor antecipado. Na conciliação, confira `splitPercentage` e compare `splitAmount` com o alvo só depois da liquidação. Essa conferência é o cenário SPL-05 da homologação. **9. Pague o lojista: o saque** O saque da subconta é pedido com a chave secreta da conta master. Ele sai por **Pix para a chave CNPJ da subconta**: a chave Pix do tipo CNPJ igual ao CNPJ do cadastro. Não é possível escolher outra chave. A moeda é sempre `BRL` e o valor vai em reais, com mínimo de R\$ 1,00. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/payout-requests" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 850.5 }' ``` ```json theme={null} { "id": "2vorkEbbbCccDddEeeFffGggHhh" } ``` O `id` devolvido é o do pedido de saque, diferente do `id` da subconta. O valor bruto sai do saldo disponível da subconta na criação. O saque nasce `pending` e sempre passa por aprovação da Finvia. A taxa de saque (`payoutFee`) é calculada na criação e soma uma parte fixa e uma percentual: `payoutFee = taxa fixa + (amount × taxa percentual ÷ 100)`. O lojista recebe `netAmount = amount − payoutFee`. > [!WARNING] > > Antes do primeiro saque, o lojista precisa cadastrar o CNPJ como chave Pix em uma conta bancária da empresa. A API não confere se a chave existe: sem ela, o Pix não é concluído e o caso precisa ser tratado com o suporte. | Resposta | Causa | | - | - | | `400` com `message` em lista | Valor inválido, por exemplo `amount must not be less than 1` | | `403` `Fast Connect not enabled.` | Connect não habilitado na conta da credencial | | `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chave de teste: não existe saque no Modo Teste | | `404` `SubMerchant not found` | Subconta inexistente ou de outra conta master | | `422` `SubMerchant account is not active` | Subconta fora de `active` | | `422` `SubMerchant is blocked. Withdrawals are not allowed.` | Subconta bloqueada | | `422` `SubMerchant CNPJ not configured` | CNPJ não cadastrado na subconta | | `422` `Insufficient balance. Required: X, Available: Y` | Saldo disponível menor que o valor | | `422` `You already have a pending withdrawal request for this currency` | Já existe um saque `pending` | | `422` `Maximum withdrawal amount is X BRL` | Acima do limite por saque configurado para a conta | | `422` `Withdrawals are disabled for this submerchant` | Saques desabilitados na subconta | | `422` `Payout fees not configured` | Taxa de saque não configurada | **10. Acompanhe o saque** O saque tem três status: `pending` (criado, valor reservado, aguardando decisão), `approved` (aprovado e enviado para pagamento) e `rejected` (recusado; o valor volta ao saldo disponível e o motivo fica em `rejectionReason`). Quando o saque de uma subconta é aprovado ou recusado, a Finvia envia `payout.approved` ou `payout.rejected` aos endpoints cadastrados na subconta e aos endpoints da conta master marcados para receber eventos das subcontas. A forma mais simples é um único endpoint na conta master, cadastrado com `include_submerchants: true` em `POST /v1/webhook-endpoints` ou com a opção de incluir subcontas em **Configurações** > **Webhooks** no painel. ```json theme={null} { "id": "2vorkEbbbCccDddEeeFffGggHhh", "event": "payout.approved", "data": { "id": "2vorkEbbbCccDddEeeFffGggHhh", "merchantId": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE", "amount": "850.50000000", "currency": "BRL", "status": "approved", "payoutFee": "1.00000000", "netAmount": "849.50000000" } } ``` O `id` da raiz é o id do saque e se repete nos eventos do mesmo saque: deduplique por `id` + `event`. `amount`, `payoutFee` e `netAmount` chegam como texto decimal com 8 casas; converta antes de somar ou exibir. O webhook de saque não tem assinatura, então confirme o status pela listagem antes de agir: ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=2vorkLm4Qp8TzR1sXc7Yb3NdWkE&status=pending&page=1&size=20" \ -u "$FINVIA_API_KEY:" ``` A resposta é `{ data, total, page, size, pages, pendingCount }`, do mais recente para o mais antigo. `pendingCount` é o total de saques pendentes com os mesmos filtros, sem considerar o de status. Cada item traz `id`, `merchantId`, `amount`, `currency`, `status`, `payoutFee`, `externalAccountDetails` (com `type` e `pix_key`), `processedAt`, `createdAt`, `merchantLegalName` e `merchantEmail`, com os valores em texto decimal. Com a chave da conta master, a listagem traz os saques de todas as subcontas: filtre por `merchantId` para ver um lojista. Também é possível filtrar por `currency` e por data de criação, com `createdAtStart` e `createdAtEnd` (`AAAA-MM-DD`). ## Quanto a Feira recebe no mês Com os números do cenário (6.500 pedidos, ticket médio de R\$ 100,00), o volume bruto é R\$ 650.000,00 e a comissão alvo é 2% disso: R\$ 13.000,00. Para simplificar, suponha 2.600 pedidos em Pix e 3.900 no cartão em 2x, com as taxas ilustrativas desta página (Pix com 1,5% e sem taxa fixa; cartão 2x com 5% e R\$ 0,40) e sem antecipação. | Pedidos | Líquido por pedido | Split informado | Feira recebe por pedido | Feira recebe no mês | | - | - | - | - | - | | 2.600 em Pix | R\$ 98,50 | 2,0305% | R\$ 2,00 | R\$ 5.200,00 | | 3.900 no cartão 2x | R\$ 94,60 | 2,1142% | R\$ 2,00 | R\$ 7.800,00 | | **Total** | | | | **R\$ 13.000,00** | Se a Feira enviasse `"percentage": 2` em todas as vendas, receberia R\$ 1,97 por pedido em Pix e R\$ 1,89 por pedido no cartão 2x: R\$ 12.493,00 no mês, R\$ 507,00 abaixo do combinado. Vendas em 3x a 6x têm outras taxas e pedem outro percentual, calculado da mesma forma. ## Liquidação e repasse do split | Tema | Como funciona | | - | - | | Cálculo | O valor de cada participante é calculado na criação da cobrança e dividido igualmente entre as parcelas | | Prazo no cartão | Cada parcela é repassada 30 dias corridos depois da criação da cobrança: 1ª parcela em D+30, 2ª em D+60 e assim por diante. No exemplo em 2x, a Feira recebe R\$ 1,00 em D+30 e R\$ 1,00 em D+60 | | Prazo no Pix | No mesmo dia, logo após a confirmação do pagamento | | Destino | O valor sai do saldo disponível do lojista e entra no saldo disponível da Feira. Antes da liquidação, o valor inteiro fica no saldo a liberar do lojista e a Feira não vê nada no saldo | | Retenção | Se a Finvia reter o recebível do lojista, a liquidação e o repasse ficam suspensos até a liberação. A parte ligada à reserva financeira do lojista é repassada quando a reserva é liberada | | Antecipação | Só o lojista, dono do recebível, antecipa. Na antecipação, o repasse acontece na hora, calculado sobre o valor já descontada a taxa de antecipação | | Estorno | Se a venda for estornada depois do repasse, a parte já repassada é debitada do saldo da Feira e devolvida ao lojista | | Cobrança recusada | O split pode aparecer na consulta, mas o repasse só acontece quando a cobrança é paga | | Assinaturas | As cobranças recorrentes de assinatura não recebem split | Duas opções existem sob consulta, configuradas pela Finvia: usar o valor bruto como base do split (aí o percentual incide sobre o bruto e não muda na antecipação) e a conta master absorver a taxa de antecipação das subcontas. Fale com o time comercial se o seu modelo precisar de uma delas. ## Regras e cuidados > [!WARNING] > > **O percentual do split incide sobre o líquido.** Repassar o mesmo percentual que a plataforma cobra sobre o bruto faz a plataforma receber menos. Calcule o percentual a cada venda com as taxas reais da subconta. > [!WARNING] > > **Saque em reais.** `"amount": 100` são R\$ 100,00. Enviar `10000` achando que é R\$ 100,00 gera um saque de R\$ 10.000,00. * **Soma dos percentuais.** Não pode passar de 100%. O que sobrar fica com o originador, a conta que criou a cobrança. * **Mesmo grupo.** Todas as contas do split precisam pertencer ao mesmo [grupo Connect](/glossario) (a conta master e as subcontas dela). Relações permitidas: conta master para subconta, subconta para conta master e subconta para subconta do mesmo grupo. * **Chave certa.** A venda criada com a chave da conta master fica na conta master. Para vincular a venda ao lojista, use a chave da subconta. * **Regra padrão de split.** No painel, na gestão de subcontas, a plataforma pode definir participantes e percentuais padrão por meio de pagamento. O `split` enviado na cobrança prevalece sobre o padrão naquela venda. * **Taxas copiadas na criação.** Mudar as taxas da conta master não muda as das subcontas já criadas. A Finvia pode replicar uma alteração para as subcontas por operação interna. * **Estorno.** É sempre da venda inteira e pedido pela conta dona da cobrança, com a chave da subconta. Quem só recebe split não consegue estornar a venda. * **Documentos depois da aprovação.** Ficam bloqueados (`422`). Revise os arquivos antes de enviar. * **URLs de documentos.** A listagem de sócios com `include=documents` devolve URLs assinadas que expiram em 1 hora. Não guarde essas URLs. ## Variações do caso > [accordion] Variação PSP: parceiro que cadastra seus lojistas como subcontas > > A **PagaFácil Serviços Digitais** é um PSP parceiro que atende 900 pequenos negócios (academias, pet shops, oficinas) e cadastra cada um deles como subconta, ganhando uma margem por transação. O desenho é o mesmo do marketplace: > > | Marketplace | PSP | > | - | - | > | Feira Online é a conta master | PagaFácil é a conta master | > | Cada lojista é uma subconta | Cada cliente da PagaFácil é uma subconta | > | Venda criada no site da Feira, com a chave do lojista | Cobrança criada pelo sistema da PagaFácil, com a chave do cliente | > | Comissão da plataforma via `split` para a conta master | Margem da PagaFácil via `split` para a conta master | > | Lojista saca para a chave CNPJ dele | Cliente saca para a chave CNPJ dele | > > As [regras de credenciamento](/guias/fast-connect/regras-de-credenciamento) pesam mais no PSP, porque ele cadastra negócios de ramos variados: > > * toda cobrança divide o valor entre a subconta e a PagaFácil, e a PagaFácil não pode ficar com 100% da venda; > * a PagaFácil confere os dados e os documentos de cada cliente antes de enviar o cadastro; > * clientes com perfil de alto risco precisam usar 3D Secure no cartão; > * o estorno é pedido só pela API (`POST /v1/refunds`); > * a análise do cadastro de cada cliente leva, em média, até 24 horas; > * clientes de MCCs vedados não podem ser credenciados. > > Outras diferenças práticas: o `productType` (`digital`, `physical` ou `both`) precisa refletir o que cada cliente vende. A PagaFácil recebe os eventos de cobrança dos clientes em um endpoint da conta master com `include_submerchants: true` e repassa a cada um. O modelo de repasse está em [Agências e white label](/casos-de-uso/white-label-agencias). > [accordion] E se o pedido tiver produtos de dois lojistas? > > Cada cobrança tem um único originador. Uma saída é criar uma cobrança por lojista no mesmo checkout, cada uma com a chave da subconta dele e o split da plataforma. Outra é criar a cobrança na subconta de um lojista e mandar a parte do outro por split de subconta para subconta, que é uma relação permitida dentro do mesmo grupo. Na segunda opção, o cálculo precisa considerar a comissão da plataforma e a parte do segundo lojista sobre o mesmo líquido. O lojista que só recebe split não recebe os eventos dessa cobrança: eles vão só para o dono da cobrança. > [accordion] E se o cliente pagar com Pix? > > O `split` funciona igual no Pix. A diferença está nas taxas e no prazo: use as linhas de `fees` com `paymentMethod` `pix` para chegar ao `f` e ao `c`, e conte com o repasse no mesmo dia, logo após a confirmação. Teste os dois métodos na homologação (cenário SPL-06). > [accordion] E se a plataforma cobrar uma taxa fixa por venda, além do percentual? > > O split aceita só percentual. Converta a taxa fixa em percentual daquela venda: some a parte fixa à comissão desejada em reais antes de dividir pelo líquido. Exemplo: comissão de 2% mais R\$ 1,00 em uma venda de R\$ 100,00 no cartão 2x dá R\$ 3,00, e `s = 3,00 ÷ 94,60 = 3,1713%`. ## Checklist de implementação * [ ] Connect habilitado pela Finvia na conta da plataforma, com as taxas da conta master definidas antes do primeiro cadastro * [ ] Regras de credenciamento conhecidas, inclusive a lista de MCCs vedados * [ ] Criação de subconta com país `BRA`, CNPJ e CPF válidos, CEP de 8 dígitos e `addressLine1` com o número depois da vírgula * [ ] Tratamento dos erros `400` e `409` na criação da subconta * [ ] Envio dos documentos de empresa e do representante; fluxo com token para sócios adicionais * [ ] Tratamento dos avisos de status, separando status que geram aviso dos que não geram, e resposta 2xx * [ ] Orientação ao lojista para corrigir dados pelo painel quando vier `correcting` * [ ] Chaves da subconta obtidas só depois de `active` e guardadas em cofre de segredos * [ ] Cálculo do percentual de split com as taxas de `fees-info`, por bandeira e parcela * [ ] Vendas criadas com a chave da subconta e `split` para a conta master * [ ] Soma dos percentuais até 100% * [ ] Conciliação do campo `splits` levando em conta a simulação de antecipação antes da liquidação * [ ] Lojistas orientados a cadastrar o CNPJ como chave Pix antes do primeiro saque * [ ] Saques em reais, com tratamento dos erros `400`, `403`, `404` e `422` * [ ] Endpoint da conta master com `include_submerchants: true` (ou endpoints nas subcontas) para os avisos de saque * [ ] Valores de saque convertidos de texto decimal e saques conferidos pela listagem ## Como homologar | Funcionalidade | Cenários | | - | - | | Subcontas | FC-01 (criar), FC-02 (documentos), FC-03 (consultar até `active`), FC-04 (chaves), FC-05 (cobrança na subconta), FC-06 (split entre subcontas), FC-07 (saque em reais), FC-08 (aviso de status) | | Split | SPL-01 (1 recebedor), SPL-02 (2 ou mais), SPL-03 (percentual inválido), SPL-04 (recebedor fora do grupo), SPL-05 (conferência do valor), SPL-06 (Pix e cartão parcelado) | SPL-01, SPL-02 e SPL-05 conferem `destinyMerchantId`, `splitPercentage` e `splitAmount` em `GET /v1/charges/{id}`. No SPL-05, compare o valor com o líquido × percentual, lembrando que antes da liquidação o `splitAmount` é uma simulação menor. O FC-07 não roda com a chave de teste, que recebe `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`: combine com o suporte da Finvia como evidenciar o saque. Detalhes no [roteiro de homologação](/homologacao/roteiro). ## Veja também > [card] [Connect](/guias/fast-connect/visao-geral) > > Conta master, subcontas e permissões. > [card] [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento) > > O que a Finvia exige de toda conta master e das subcontas. > [card] [Cálculo de split](/guias/fast-connect/calculo-split) > > Fórmula e código para comissão sobre o bruto. > [card] [Saques](/guias/fast-connect/saques) > > Saque da subconta, taxas e acompanhamento. # SaaS por assinatura Source: https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas Software cobrado todo mês no cartão: planos, trial, cartão salvo, renovação automática, retentativas, troca de plano, cancelamento e controle de acesso por webhook. Uma empresa de software por assinatura precisa cobrar o cliente automaticamente a cada ciclo, sem pedir o cartão de novo, e manter o acesso ao sistema alinhado com a situação do pagamento: liberar quando entra, avisar quando falha, bloquear quando a assinatura acaba. Esta página mostra como montar esse ciclo com as assinaturas da Finvia. > [!TIP] > > Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](/integrar-com-ia). Implementar este caso com um assistente de IA Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md) * [https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md) * [https://docs.fastpaybrasil.com/guias/assinaturas/planos.md](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md) * [https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) * [https://docs.fastpaybrasil.com/guias/clientes.md](https://docs.fastpaybrasil.com/guias/clientes.md) * [https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) * [https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md) * [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar neste projeto o fluxo descrito na página "SaaS por assinatura" ([https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md)). Resumo do caso: Software cobrado todo mês no cartão: planos, trial, cartão salvo, renovação automática, retentativas, troca de plano, cancelamento e controle de acesso por webhook. Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## O cenário A **Agenda Clara** é um software de agendamento para salões de beleza e barbearias, com sede em Recife. Ela tem 2.400 clientes pagantes e três planos: | Plano | Preço | O que inclui | | - | - | - | | Essencial | R\$ 59,90 por mês | 1 profissional | | Equipe | R\$ 129,90 por mês | Até 5 profissionais | | Rede | R\$ 299,90 por mês | Profissionais ilimitados e várias unidades | Todo cliente novo ganha **14 dias grátis** para testar. A Agenda Clara quer cobrar no cartão de crédito, renovar sozinha todo mês e bloquear o acesso de quem deixar de pagar, sem planilha e sem cobrança manual. ## O que a Finvia resolve > [!NOTE] > > **Para o negócio:** a assinatura liga um cliente, um plano e um cartão guardado no cofre da Finvia. A partir daí, a Finvia cobra sozinha a cada ciclo, tenta de novo quando a cobrança é recusada e envia um webhook a cada mudança: ativação, renovação, falha, cancelamento e expiração. O sistema da Agenda Clara usa esses avisos para liberar ou bloquear o acesso. Pela regra da plataforma, o cancelamento em até 7 dias da criação da assinatura estorna automaticamente as cobranças pagas dela. ## Arquitetura da solução | Necessidade | Recurso | Rota ou guia | | - | - | - | | Definir preço e periodicidade | Plano de assinatura | `POST /v1/subscription-plans` · [Planos](/guias/assinaturas/planos) | | Período de teste | Objeto `trial` no plano | `POST /v1/subscription-plans` | | Cadastro do pagador | Cliente com e-mail e CPF ou CNPJ | `POST /v1/customers` · [Clientes](/guias/clientes) | | Guardar o cartão | Cofre de cartões (fluxo cards-first) | `POST /v1/cards` · [Cofre de cartões](/guias/cofre-de-cartoes) | | Cobrança automática | Assinatura | `POST /v1/subscriptions` · [Assinaturas](/guias/assinaturas/visao-geral) | | Liberar e bloquear acesso | Webhooks `subscription.*` | [Webhooks de assinatura](/guias/webhooks/assinatura) | | Histórico de cobranças | Consulta da assinatura | `GET /v1/subscriptions/{id}` | | Cancelamento | Cancelar assinatura | `POST /v1/subscriptions/{id}/cancel` · [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) | > [!WARNING] > > Assinaturas não têm modo de teste: com a chave de teste, as cobranças da assinatura acontecem de verdade, inclusive a validação de R\$ 1,00 do trial grátis. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). O desenho abaixo mostra quem faz o quê na assinatura da Agenda Clara, da criação dos planos ao controle de acesso. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB C(["Salão ou barbearia
contrata um plano"]):::comprador S["Servidor da Agenda Clara
chave secreta sk_"]:::lojista API["Finvia API"]:::finvia COF["Cofre de cartões
cartão nasce active"]:::finvia MOT["Renovação automática
rodadas às 6h, 12h e 18h"]:::finvia ADQ["Adquirente e bandeiras
cartão de crédito"]:::externo EV[["Eventos subscription.*
activated · renewed
payment_failed · expired"]]:::evento W["Receptor de webhooks
endpoint cadastrado"]:::lojista AC["Controle de acesso
da Agenda Clara"]:::lojista OK(["Acesso liberado até
current_period_end"]):::ok S -->|"1. cria os planos
/v1/subscription-plans"| API C -->|"2. escolhe o plano
e informa o cartão"| S S -->|"3. POST /v1/customers
e POST /v1/cards"| API S ==>|"4. POST /v1/subscriptions
plano · cliente · cartão"| API API -->|"5. guarda o cartão"| COF API -->|"6. agenda os ciclos"| MOT MOT -->|"7. cobra no fim do trial
e a cada mês"| ADQ API -->|"8. publica o evento"| EV EV -.->|"9. entrega"| W W -->|"10. libera, avisa
ou bloqueia"| AC AC ==> OK classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Este segundo desenho acompanha a vida de uma assinatura no plano com 14 dias grátis: validação do cartão, renovações, retentativas e cancelamento. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["POST /v1/subscriptions
plano com 14 dias grátis"]):::neutro V{"Validação de
R$ 1,00 no cartão?"}:::decisao E422["422
CARD_VALIDATION_FAILED
nada é criado"]:::erro ACT["active
subscription.activated
libera o acesso"]:::ok REN{"Cobrança
do ciclo?"}:::decisao RNW["active
subscription.renewed
estende o acesso"]:::ok PF["active
subscription.payment_failed
avisa e mantém o acesso"]:::alerta EXP["expired
subscription.expired
bloqueia o acesso"]:::erro CAN{"Cancelou até 7 dias
da criação?"}:::decisao REG["cancelled · regret
estorna as pagas
e bloqueia na hora"]:::erro REGU["cancelled · regular
sem estorno, acesso
até current_period_end"]:::neutro INI --> V V -->|"recusada ou
em análise"| E422 V ==>|"aprovada e
estornada em seguida"| ACT ACT ==>|"fim do trial e,
depois, de cada mês"| REN REN ==>|"aprovada"| RNW RNW -.->|"próximo ciclo"| REN REN -->|"recusada"| PF PF -->|"nova rodada
6h · 12h · 18h"| REN PF -->|"limite de tentativas
do ciclo"| EXP ACT -->|"cliente pede
o cancelamento"| CAN CAN -->|"sim"| REG CAN -->|"não"| REGU classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Em plano sem trial, a primeira mensalidade é cobrada na criação, e uma recusa deixa a assinatura em `pending_activation`, como mostra o passo "Trate a resposta da criação". ## Passo a passo **1. Confira o perfil de quem gera a chave** A chave de API age com o perfil do usuário que a gerou. Para integrar assinaturas, gere a chave com um usuário **Owner** ou **Manager**. Os perfis Desenvolvedor e Financeiro recebem `403` `Acesso negado` em todas as rotas de planos e assinaturas, e o perfil Visualizador só acessa as consultas. **2. Crie os planos** Cada plano define nome, preço em reais, moeda e recorrência. Planos cobrados no cartão aceitam só `BRL`. O `merchantId` é o ID da sua conta na Finvia. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "2v2TGGb4NHTQWCiMmnelz2WVOZP", "name": "Agenda Clara Equipe Mensal", "price": 129.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao plano Equipe da Agenda Clara!", "paymentMethods": ["credit_card"], "trial": { "durationDays": 14, "isFree": true }, "status": "active" }' ``` A resposta `201` traz só o `id` do plano. Para ver o plano completo, use `GET /v1/subscription-plans/{id}`. Repita para Essencial e Rede. > [!NOTE] > > Editar um plano depois (`PUT /v1/subscription-plans/{id}`) **não muda** as assinaturas existentes: preço e periodicidade ficam congelados na assinatura no momento da contratação. A edição vale só para assinaturas novas. **3. Cadastre o cliente** Para registrar cartão, o cliente precisa de **e-mail** e de **CPF ou CNPJ**. A API identifica o tipo pela quantidade de dígitos do documento: 11 é CPF e 14 é CNPJ. Passaporte ou RG contam como "sem documento", e o registro do cartão é recusado com `400` `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador`. Como a Agenda Clara atende empresas, ela usa o CNPJ do salão quando houver. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "name": "Salão Bela Ana", "email": "ana@email.com", "documentId": "11222333000181", "documentType": "cnpj", "phoneNumber": "+5511987654321" }' ``` **4. Registre o cartão (cards-first)** O fluxo recomendado é registrar o cartão antes de criar a assinatura. O cartão já nasce `active`, sem transação de teste e sem etapa de ativação. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/cards" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "1111222233334444", "holderName": "ANA LIMA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123" }' ``` ```json theme={null} { "id": "2RhQgK4vN8pT1wZ6yB3mC7dF", "token": "tok_abc123xyz", "maskedNumber": "****4444", "status": "active", "pendingActivation": false } ``` O cartão pertence ao merchant da chave que o registrou. Ele não pode ser usado por outra conta ou subconta. O registro é real mesmo com a chave de teste, mas não cobra nada. **5. Crie a assinatura** Com plano, cliente e cartão, a assinatura é criada com três IDs diferentes: o do plano, o do cliente e o do cartão. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "cardTokenId": "2RhQgK4vN8pT1wZ6yB3mC7dF", "metadata": { "contaAgendaClara": "AC-55821" } }' ``` O que acontece depende do trial do plano: | Plano | O que a Finvia faz na criação | | - | - | | Trial grátis (`isFree: true`) | Cobra R\$ 1,00 para validar o cartão e estorna em seguida. A mensalidade só é cobrada no fim do trial | | Trial pago (`isFree: false`) | Cobra o valor do trial na criação | | Sem trial | Cobra a primeira mensalidade cheia na criação | | `skipTrial: true` na assinatura | Ignora o trial do plano e cobra o valor cheio na criação | No trial grátis, se a cobrança de R\$ 1,00 for recusada, ficar em análise ou ficar sem resposta do processador, a API responde `422` com `code` `CARD_VALIDATION_FAILED` e nada é criado: nem assinatura, nem webhook. A `message` traz o motivo no formato `Não foi possível validar o cartão: `. Decida o fluxo pelo `code` e use a `message` só para exibir. Reenviar a mesma requisição (mesmo cliente, cartão e plano) em até 15 minutos reaproveita uma validação aprovada sem cobrar R\$ 1,00 de novo. Com sucesso, a resposta `201` traz `cardValidation: { "validated": true, "amount": 1 }`. > [!TIP] > > **Para o desenvolvedor:** avise no checkout que o cliente pode ver uma cobrança de R\$ 1,00 e o estorno na fatura. O estorno é feito logo depois, de forma assíncrona. **6. Trate a resposta da criação** | Resposta | Significado | O que fazer | | - | - | - | | `status` `active` | Assinatura ativa | Liberar o acesso | | `status` `pending_activation` e `firstCharge.success: false` | Primeira cobrança recusada | Pedir outro cartão e criar uma nova assinatura | | `status` `pending_activation` e `firstCharge.pending: true` | Pagamento em análise | **Não** criar outra assinatura. Aguardar `subscription.activated` ou `subscription.payment_failed` | | `422` `CARD_VALIDATION_FAILED` | Validação do trial grátis recusada, em análise ou sem resposta | Pedir outro cartão | | `409` `CARD_VALIDATION_IN_PROGRESS` | A mesma validação já está em andamento (requisição repetida em paralelo) | Aguardar a primeira requisição | | `429` `CARD_VALIDATION_RATE_LIMITED` | 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na conta em 1 hora | Pedir outro cartão e esperar antes de tentar de novo | | `404` "Subscription plan not found or inactive" | Plano inexistente ou inativo | Conferir o plano com `GET /v1/subscription-plans/{id}` | | `403` `Acesso negado` | O perfil de quem gerou a chave não tem permissão | Gerar a chave com Owner ou Manager | Uma assinatura em `pending_activation` não cobra, não renova e não tem retentativa automática. Ela só passa a `active` sozinha quando a primeira cobrança estava em análise e a análise aprovou. Se a cobrança foi recusada, a API não tenta de novo: para outra tentativa (por exemplo, com outro cartão), crie uma nova assinatura com `POST /v1/subscriptions`. A nova terá outro `id`. A pendente pode ser cancelada com `POST /v1/subscriptions/{id}/cancel` para não ficar na listagem. **7. Controle o acesso pelos webhooks** Cadastre o endpoint no painel, em **Configurações** > **Webhooks**, ou pela API em `POST /v1/webhook-endpoints`. Assinaturas não têm `postbackUrl`: os eventos chegam só aos endpoints. Eles usam o envelope padrão (`id`, `event`, `livemode`, `data`), com campos em snake\_case; o objeto `trial` vem em camelCase e o `metadata` volta como foi enviado. ```javascript theme={null} app.post('/webhooks/finvia', async (req, res) => { const { id, event, data } = req.body; if (await eventos.jaProcessado(id)) return res.status(200).send('OK'); res.status(200).send('OK'); const conta = data.metadata?.contaAgendaClara; switch (event) { case 'subscription.activated': case 'subscription.renewed': await acesso.liberarAte(conta, data.current_period_end); break; case 'subscription.payment_failed': // A assinatura continua active durante as retentativas await avisos.pedirAtualizacaoDeCartao(conta, data.failure_reason); break; case 'subscription.cancelled': if (data.cancellation_type === 'regret') await acesso.bloquearAgora(conta); else await acesso.liberarAte(conta, data.current_period_end); break; case 'subscription.expired': await acesso.bloquearAgora(conta); break; } await eventos.marcarProcessado(id); }); ``` | Evento | Quando chega | Ação na Agenda Clara | | - | - | - | | `subscription.created` | Assinatura criada | Registrar | | `subscription.activated` | Primeira cobrança aprovada, inclusive depois de uma análise; no trial grátis, já na criação, sem o objeto `charge` | Liberar acesso | | `subscription.renewed` | Cobrança do ciclo aprovada, inclusive a primeira cheia após o trial | Estender acesso até `current_period_end` | | `subscription.payment_failed` | Cada tentativa de cobrança recusada, inclusive a primeira | Avisar o cliente; manter acesso | | `subscription.cancelled` | Assinatura cancelada | `regret`: bloquear o acesso imediatamente. `regular`: manter até `current_period_end` | | `subscription.expired` | Retentativas esgotadas ou plano chegou ao `endDate` | Bloquear acesso | > [!NOTE] > > Os eventos `subscription.trial_started` e `subscription.trial_ended` existem no contrato de tipos, mas **não são entregues** hoje. Acompanhe o trial pelos eventos `subscription.activated` e `subscription.renewed`, que trazem o objeto `trial`. **8. Acompanhe renovações e retentativas** O ciclo fica ancorado na data e hora da contratação. Com trial, a referência passa a ser o fim do trial, quando a primeira mensalidade é cobrada. No plano mensal, o dia de referência é mantido: uma contratação em 31/01 renova em 28/02 (ou 29/02) e volta para 31/03. A renovação é feita por uma rotina que roda às 6h, 12h e 18h (horário de Brasília), depois do fim do período (`current_period_end`). O novo período começa exatamente no fim do anterior, então esse intervalo de algumas horas não desloca o ciclo. Se a cobrança for recusada: * as rodadas seguintes tentam de novo; * cada recusa gera `subscription.payment_failed`, com `failure_reason` em texto (ex.: `"Cartão vencido"`); * ao atingir o limite de tentativas do ciclo, a assinatura vira `expired` e chega `subscription.expired`. O calendário exato das retentativas e o limite por ciclo estão em [Ciclo de vida](/guias/assinaturas/ciclo-de-vida). Para ver o histórico, consulte a assinatura: ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W3kZ0S" \ -u "$FINVIA_API_KEY:" ``` A resposta traz `charges`, com uma linha por tentativa, do ciclo mais recente para o mais antigo. Cada linha tem `billingCycle`, valor e status (`pending`, `paid`, `failed` ou `refunded`). As retentativas recusadas de um ciclo repetem o mesmo `billingCycle`, e `billingCycle: 0` é a cobrança do trial pago. > [!NOTE] > > O `charges[].id` é o id do registro de cobrança da assinatura (o mesmo valor de `data.charge.id` nos webhooks de assinatura). Ele não funciona em `GET /v1/charges/{id}`. O id da cobrança aparece em `firstCharge.chargeId` e `trialCharge.chargeId` na criação, em `data.charge.charge_id` nos webhooks de assinatura e em `data[].chargeId` na listagem `GET /v1/subscription-plans/{id}/charges`. **9. Troque de plano ou de cartão** A assinatura não permite trocar plano, cartão ou valor, nem pausar. Só `metadata` pode ser alterado, e só em assinatura `active`. Para o cliente que sobe do Essencial para o Equipe, a Agenda Clara: 1. cancela a assinatura atual com `POST /v1/subscriptions/{id}/cancel`; 2. cria uma assinatura nova no plano Equipe, com `skipTrial: true` para não dar outro período grátis. ```json theme={null} { "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "cardTokenId": "2RhQgK4vN8pT1wZ6yB3mC7dF", "skipTrial": true, "metadata": { "contaAgendaClara": "AC-55821", "trocaDe": "essencial" } } ``` A nova assinatura começa um ciclo novo, com cobrança imediata do valor cheio. A Finvia não calcula valor proporcional: se quiser compensar dias já pagos no plano antigo, faça isso na sua política comercial. > [!WARNING] > > Se a troca acontecer **nos primeiros 7 dias** da assinatura antiga, o cancelamento entra como arrependimento (`regret`) e estorna automaticamente todas as cobranças pagas dela. Considere isso antes de trocar o plano de um cliente recém-contratado. **10. Cancele quando o cliente pedir** ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W3kZ0S/cancel" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "reason": "Cliente encerrou o salão" }' ``` `reason` é opcional, com no máximo 500 caracteres. O resultado depende do prazo, contado em dias completos desde a criação da assinatura. É uma regra da plataforma, aplicada a todo cancelamento, venha ele de você ou da Finvia: | Quando | `cancellationType` | Estorno | Acesso | | - | - | - | - | | Até 7 dias da criação | `regret` | Todas as cobranças pagas são estornadas (`refunded: true`; `false` se não havia cobrança paga, como no trial grátis, ou se um estorno não foi concluído) | Revogado imediatamente | | Depois de 7 dias | `regular` | Nenhum (`refunded: false`) | O status já é `cancelled` e as cobranças param. `accessRevokedAt` indica até quando o acesso pago vale, e a Agenda Clara controla esse prazo | Não existe opção para cancelar nos primeiros 7 dias sem estornar. Cancelar uma assinatura já cancelada ou expirada retorna `400` "Subscription already cancelled or expired". ## Regras e cuidados > [!WARNING] > > **Não use cartão salvo em `POST /v1/charges` para cobrar todo mês.** Nessa rota, o CVV do comprador é obrigatório a cada cobrança, então ela não cobra com o cliente ausente. A cobrança recorrente automática é feita pelas assinaturas. * **Permissão da chave.** Desenvolvedor e Financeiro recebem `403` em todas as rotas de planos e assinaturas; Visualizador só nas consultas. * **Moeda.** Planos cobrados no cartão aceitam só `BRL`. * **Trial grátis valida com R\$ 1,00.** A cobrança é real, também com a chave de teste. O cliente pode ver a cobrança e o estorno na fatura. Avise no checkout. * **`pending_activation` não cobra nem renova.** Se a análise aprovar o pagamento, a assinatura passa a `active` sozinha. Se a cobrança foi recusada, crie uma nova assinatura. Não crie outra enquanto `firstCharge.pending` for `true`. * **Acesso no cancelamento regular é sua responsabilidade.** A Finvia para de cobrar imediatamente e informa a data limite em `accessRevokedAt` (e em `current_period_end` no webhook). * **`failure_reason` é texto.** Use para exibir ou registrar, nunca para decidir o fluxo. * **Correlação com cobranças.** Cada cobrança paga da assinatura também gera `charge.created` e `charge.paid`. No evento de assinatura, `data.charge.charge_id` é o ID da cobrança (o mesmo de `GET /v1/charges/{id}`). No `charge.paid`, o `metadata` traz `subscription_id` e `billing_cycle`. * **Recusa não gera `charge.*`.** A falha de uma cobrança de assinatura é avisada só por `subscription.payment_failed`. * **Sem split.** As cobranças recorrentes das assinaturas não recebem split. Se um parceiro tiver direito a parte da mensalidade, o repasse precisa ser feito por outro caminho. ## Variações do caso > [accordion] E se a empresa quiser plano anual? > > O contrato oferece `weekly`, `biweekly`, `monthly` e `custom`. Um plano anual usa `recurrenceType: "custom"` com `recurrenceInterval`, um número inteiro de **dias** corridos (por exemplo, `365`). O `custom` só soma dias, então "a cada 365 dias" desliza um dia no calendário em anos bissextos. Nos tipos `weekly`, `biweekly` e `monthly`, `recurrenceInterval` é ignorado. > [accordion] E se o cliente não quiser cartão? > > As assinaturas cobram só no cartão. Para quem paga por Pix, o sistema da Agenda Clara pode gerar todo mês uma cobrança Pix avulsa com `POST /v1/charges` e controlar o acesso pelo `charge.paid`. O desenho está em [Educação e mensalidades](/casos-de-uso/educacao-mensalidades), na variação de Pix mensal. > [accordion] E se a empresa quiser criar a assinatura em uma chamada só? > > Dá para enviar o objeto `customer` (com `name`, `email` e `document` do tipo `cpf` ou `cnpj`) e o cartão em `paymentMethod` direto em `POST /v1/subscriptions`. A API localiza o cliente pelo e-mail ou cria um novo, e registra o cartão. Se já existir um cliente com o mesmo e-mail, vale o documento do cadastro dele, e não o da requisição. Use `customerId` **ou** `customer`, e `cardTokenId` **ou** `paymentMethod`, nunca os dois. > [accordion] E se a empresa quiser escolher o dia da cobrança? > > Hoje não é possível escolher o dia de cobrança. O ciclo fica ancorado na data da contratação (ou no fim do trial), e o campo `billingDay` não existe mais: se for enviado, é ignorado sem erro. Para alinhar o ciclo a um dia do mês, crie a assinatura nesse dia. > [accordion] E se o cartão do cliente vencer? > > A tentativa chega como `subscription.payment_failed`, e `charge.charge_id` pode vir `null` quando a tentativa nem foi enviada à cobrança (cartão vencido ou indisponível). Essa tentativa conta para o limite. Peça um cartão novo, registre-o, cancele a assinatura atual e crie outra. ## Checklist de implementação * [ ] Chave gerada por Owner ou Manager (Desenvolvedor e Financeiro recebem `403` nas assinaturas) * [ ] Planos criados em `BRL`, com o trial definido, e `id` lido da resposta `201` * [ ] Cliente cadastrado com e-mail e CPF ou CNPJ * [ ] Cartão registrado com `POST /v1/cards` e `status` `active` * [ ] Aviso no checkout sobre a validação de R\$ 1,00 no trial grátis * [ ] Tratamento de `active`, `pending_activation`, `firstCharge.pending` e dos códigos `CARD_VALIDATION_FAILED`, `CARD_VALIDATION_IN_PROGRESS` e `CARD_VALIDATION_RATE_LIMITED` * [ ] Nova assinatura criada para tentar de novo depois de uma primeira cobrança recusada * [ ] Endpoint de webhook com idempotência persistente pelo `id` do evento * [ ] Acesso liberado em `activated` e `renewed`, bloqueado em `expired` e no cancelamento `regret` * [ ] Acesso mantido até `current_period_end` no cancelamento `regular` * [ ] Comunicação ao cliente a cada `subscription.payment_failed` * [ ] Troca de plano feita com cancelamento e nova assinatura, considerando a janela de 7 dias * [ ] Homologação com cartão real de valor baixo e cancelamento no mesmo dia ## Como homologar Os cenários SUB-01 a SUB-06 cobrem o fluxo: registrar cartão, cobrança com cartão salvo, criar plano, criar assinatura, receber `subscription.created` e `subscription.activated` e cancelar em até 7 dias conferindo `cancellationType: "regret"` e `refunded: true`. Com a chave de teste, a cobrança com cartão salvo (SUB-02) é simulada, mas o cadastro do cartão e as assinaturas são reais: use cartão real com valor baixo e cancele no mesmo dia. Detalhes no [roteiro de homologação](/homologacao/roteiro). ## Veja também > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e desativação de planos. > [card] [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida) > > Status, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Payload de cada evento. > [card] [Criar assinatura](/referencia/assinaturas/criar) > > Referência completa da rota. # Casos de uso Source: https://docs.fastpaybrasil.com/casos-de-uso/visao-geral Oito modelos de negócio montados sobre a API da Finvia, com os recursos que cada um usa e como escolher o seu ponto de partida. Cada caso de uso desta seção parte de uma empresa fictícia brasileira, com números plausíveis. Ele mostra como a empresa monta a operação de pagamentos com a API da Finvia: quais rotas chama, em que ordem, o que acontece em cada etapa, quais regras limitam o desenho e o que testar antes de ir para produção. Os casos foram escritos para dois leitores ao mesmo tempo. O analista de negócios encontra o cenário, o que o recurso faz e as regras que afetam o produto. O desenvolvedor encontra a arquitetura, as requisições válidas contra o contrato da API e os cenários de homologação. > [!NOTE] > > **Para o negócio:** os casos mostram o que a API faz hoje. Nenhum deles promete resultado de vendas, de aprovação ou de custo. Os detalhes de cada recurso, com todas as regras e erros, ficam nos guias indicados em cada página. ## Os oito casos > [card] [E-commerce](/casos-de-uso/e-commerce) > > Loja virtual de produtos físicos: Pix com validade curta, cartão parcelado, Apple Pay, 3DS, entrega, estorno e recompra. > [card] [SaaS por assinatura](/casos-de-uso/saas-assinaturas) > > Software com plano mensal: trial, cartão salvo, renovação automática, retentativas e controle de acesso por webhook. > [card] [Marketplace e PSP](/casos-de-uso/marketplace-psp) > > Plataforma com vários vendedores: subcontas, KYC, split com comissão sobre o bruto e saques dos vendedores. > [card] [Infoprodutos](/casos-de-uso/infoprodutos) > > Cursos e produtos digitais: Pix e cartão parcelado, liberação de acesso só após confirmação, reembolso e coprodução. > [card] [ERP e software de gestão](/casos-de-uso/erp-software-de-gestao) > > Sistema que cobra em nome dos próprios clientes: cada cliente vira subconta, com conciliação e onboarding em massa. > [card] [Cobrança por mensagem](/casos-de-uso/cobranca-por-link) > > Venda pelo WhatsApp, Instagram ou telefone: Pix gerado pela API e enviado por mensagem, com confirmação por webhook. > [card] [Agências e white label](/casos-de-uso/white-label-agencias) > > Agência que monta um gateway próprio para os clientes: conta master, subcontas, chaves por cliente e repasse de eventos. > [card] [Educação e mensalidades](/casos-de-uso/educacao-mensalidades) > > Escolas e cursos: mensalidade por assinatura, Pix avulso para matrícula e material, inadimplência e cancelamento. ## Qual recurso cada caso usa A Finvia recebe por **cartão de crédito** (digitado, salvo no cofre ou pelo Apple Pay) e por **Pix**. Todos os casos usam só esses dois meios. Na tabela, **Sim** indica que o recurso faz parte do fluxo principal do caso, **Opcional** indica que aparece em uma variação ou melhora o fluxo, e **Não** indica que o caso não depende dele. | Recurso | E-commerce | SaaS | Marketplace e PSP | Infoprodutos | ERP | Cobrança por mensagem | White label | Educação | | - | - | - | - | - | - | - | - | - | | Cobrança Pix | Sim | Opcional | Sim | Sim | Sim | Sim | Sim | Sim | | Cartão de crédito | Sim | Opcional | Sim | Sim | Sim | Opcional | Sim | Sim | | Cartão salvo | Sim | Sim | Opcional | Opcional | Opcional | Não | Opcional | Sim | | Apple Pay | Sim | Não | Opcional | Opcional | Não | Não | Opcional | Não | | 3D Secure | Sim | Não | Opcional | Opcional | Não | Não | Opcional | Não | | Assinaturas | Não | Sim | Não | Opcional | Opcional | Não | Opcional | Sim | | Connect e split | Não | Não | Sim | Opcional | Sim | Não | Sim | Opcional | | Saques | Não | Não | Sim | Opcional | Sim | Não | Sim | Não | | Webhooks | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Onde cada recurso está documentado: | Recurso | Guia | Rota principal | | - | - | - | | Cobrança Pix | [Pix](/guias/cobrancas/pix) | `POST /v1/charges` com `paymentMethod.type` `pix` | | Cartão de crédito | [Cartão de crédito](/guias/cobrancas/cartao-de-credito) | `POST /v1/charges` com `paymentMethod.type` `credit_card` | | Cartão salvo | [Cofre de cartões](/guias/cofre-de-cartoes) | `POST /v1/cards` e `POST /v1/charges` com `cardTokenId` | | Apple Pay | [Apple Pay](/guias/cobrancas/apple-pay) | `POST /v1/charges` com `paymentMethod.wallet` | | 3D Secure | [3D Secure](/guias/3d-secure/visao-geral) | `POST /v1/charges` com `threeDSMode` ou `threeDS` | | Assinaturas | [Assinaturas](/guias/assinaturas/visao-geral) | `POST /v1/subscription-plans` e `POST /v1/subscriptions` | | Connect e split | [Connect](/guias/fast-connect/visao-geral) | `POST /v1/submerchants` e campo `split` em `POST /v1/charges` | | Saques de subcontas | [Saques de subcontas](/guias/fast-connect/saques) | `POST /v1/submerchants/{merchantId}/payout-requests` | | Saque da própria conta | [Saldos e saques](/guias/saldos-e-meios-de-pagamento) | `POST /v1/payout-requests` | | Webhooks | [Webhooks](/guias/webhooks/visao-geral) | Endpoints cadastrados no painel ou em `POST /v1/webhook-endpoints`, e `postbackUrl` da cobrança | ## Como escolher Comece pela pergunta que define a arquitetura: **o dinheiro da venda é só seu, ou é de outras empresas que vendem pela sua plataforma?** O desenho abaixo resume essa escolha: duas perguntas levam ao caso de uso mais próximo do seu negócio e aos blocos da API que ele usa. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Seu negócio vende
pela API da Finvia"]):::neutro Q1{"De quem é o
dinheiro da venda?"}:::decisao Q2{"Como você
cobra?"}:::decisao A["E-commerce
Infoprodutos
Pix, cartão, Apple Pay"]:::neutro B["SaaS e Educação
assinatura no cartão
e Pix avulso"]:::neutro C["Cobrança por mensagem
Pix enviado
na conversa"]:::neutro CON["Connect
você é a conta master
e cada empresa, subconta"]:::finvia Q3{"Quem são
essas empresas?"}:::decisao D["Marketplace e PSP
KYC, split e saques
dos vendedores"]:::neutro E["ERP e gestão
subconta por cliente
e baixa por webhook"]:::neutro F["White label
chaves por cliente
e repasse de eventos"]:::neutro INI --> Q1 Q1 -->|"só da sua empresa"| Q2 Q1 -->|"de outras empresas"| CON Q2 --->|"venda avulsa
no site ou app"| A Q2 --->|"automática
a cada ciclo"| B Q2 --->|"fechada
na conversa"| C CON --> Q3 Q3 -->|"vendedores de
uma vitrine"| D Q3 -->|"clientes do
seu software"| E Q3 -->|"clientes da
sua agência"| F classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Todos os casos usam webhooks para saber quando o pagamento entrou. Os passos abaixo detalham cada caminho. **1. O dinheiro é só da sua empresa** Você é o merchant e cobra os seus próprios clientes. Escolha pelo modelo de cobrança: * Venda avulsa com o cliente no site ou no app: [E-commerce](/casos-de-uso/e-commerce) ou [Infoprodutos](/casos-de-uso/infoprodutos). * Cobrança automática a cada ciclo: [SaaS por assinatura](/casos-de-uso/saas-assinaturas) ou [Educação e mensalidades](/casos-de-uso/educacao-mensalidades). * Venda sem site, fechada por conversa: [Cobrança por mensagem](/casos-de-uso/cobranca-por-link). **2. O dinheiro é de outras empresas** Cada empresa que vende pela sua plataforma precisa da própria conta, com cadastro e KYC. Na Finvia, isso é feito com o módulo Connect: a sua empresa vira a conta master (MerchantMaster) e cada vendedor vira uma subconta (SubMerchant). * Vários vendedores em uma vitrine única: [Marketplace e PSP](/casos-de-uso/marketplace-psp). * Software que já atende empresas e passa a cobrar em nome delas: [ERP e software de gestão](/casos-de-uso/erp-software-de-gestao). * Agência que monta a operação de pagamentos para vários clientes: [Agências e white label](/casos-de-uso/white-label-agencias). **3. Combine quando precisar** Os casos se combinam. Uma escola com várias unidades pode usar assinaturas em cada subconta. Um marketplace de cursos pode usar a lógica de liberação de acesso dos infoprodutos. Use a tabela acima para ver quais recursos entram na sua combinação. ## Regras que valem para todos os casos | Regra | O que significa | | - | - | | Valores em reais | `"amount": 10` é R\$ 10,00. Enviar `1000` pensando em R\$ 10,00 gera uma cobrança de R\$ 1.000,00 | | Endereço de entrega para produto físico | Se algum item for `physical`, `shippingAddress` é obrigatório. Sem ele, a API responde `400` com `Shipping info must be provided for merchants selling physical items.`. No endereço, `postalCode`, `addressLine1`, `city`, `state` e `country` (três letras, como `BRA`) são obrigatórios; `addressLine2` e `neighborhood` são opcionais | | Sem `Idempotency-Key` | Cada `POST /v1/charges` cria uma cobrança nova. Depois de um timeout, não reenvie de imediato: recupere a cobrança pelo webhook `charge.created` ou pela listagem, como em [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia) | | `metadata` em camelCase | Os exemplos desta seção usam chaves em camelCase ou de uma palavra só, que voltam iguais em todos os canais. Veja [Metadata](/guias/cobrancas/visao-geral#metadata) | | Webhooks sem assinatura HMAC | Confirme o estado real na API (`GET /v1/charges/{id}`) antes de liberar produto, acesso ou dinheiro | | Teste e produção no mesmo endpoint | Os endpoints de webhook recebem eventos de teste e de produção. Nas cobranças, separe pelo campo `livemode` (`false` no teste) | | Permissão da chave | A chave age com o perfil do usuário que a gerou. O perfil Desenvolvedor recebe `403` ao criar cobrança, nas rotas de assinatura, no saldo e nos saques. Gere a chave com um usuário Owner ou Manager | Os exemplos usam a URL base da API, `https://api-global.fastpaybrasil.com`. O painel fica em `https://app.finvia.com.br`, e as chaves estão em **Configurações** > **Chave de API**. ## Como testar no Modo Teste Com a chave de teste (`sk_test_`), toda cobrança criada em `POST /v1/charges` é simulada e não movimenta dinheiro. Os outros recursos têm regras próprias: | Recurso | Como se comporta com a chave de teste | | - | - | | Pix | A cobrança nasce `pending` com um QR Code fictício e passa sozinha para `paid` cerca de 5 segundos depois. Não tente pagar o código no app do banco. Não há como simular expiração | | Cartão digitado | O resultado depende do número: `4444333322221111` aprova, `4444333322221112` recusa (`card_declined`), um número terminado em `2222` fica `pending` e qualquer outro número aprova. Envie o número só com dígitos | | Cartão salvo (`cardTokenId`) | A cobrança é simulada. O cadastro do cartão em `POST /v1/cards` é real, mas não cobra nada | | Assinaturas | São reais: as cobranças acontecem de verdade, inclusive a validação de R\$ 1,00 do trial grátis | | Saques | Não existem no Modo Teste. A criação responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | | Webhooks | As cobranças de teste chegam com `livemode: false`. O reenvio de webhook de teste dispara um evento novo com o status escolhido e não altera a cobrança | > [!WARNING] > > O cofre de cartões é o mesmo para teste e produção. Um `cardTokenId` criado na homologação também funciona com a chave de produção, e aí a mesma chamada cobra de verdade. O detalhe está em [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes). ## Como cada caso está organizado Todas as páginas seguem a mesma ordem, para facilitar a comparação: 1. **O cenário**: a empresa fictícia, o que ela vende e o problema de pagamento. 2. **O que a Finvia resolve**: o que os recursos fazem nesse contexto. 3. **Arquitetura da solução**: tabela com necessidade, recurso e rota. 4. **Passo a passo**: requisições reais, válidas contra o contrato. 5. **Regras e cuidados**: o que causa erro, cobrança indevida ou perda de dinheiro. 6. **Variações do caso**: alternativas comuns do mesmo modelo. 7. **Checklist de implementação** e **Como homologar**, com os códigos de cenário do [roteiro de homologação](/homologacao/roteiro). ## Veja também > [card] [Conceitos](/conceitos) > > Cobrança, cliente, subconta, split, webhook e postback. > [card] [Sua primeira cobrança](/primeiros-passos/primeira-cobranca) > > Uma cobrança Pix completa em poucos minutos. > [card] [Roteiro de homologação](/homologacao/roteiro) > > Cenários obrigatórios por funcionalidade. > [card] [Checklist de go-live](/homologacao/checklist-go-live) > > O que conferir antes de virar para produção. # Agências e plataformas white label Source: https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias Agência ou plataforma que monta um gateway próprio sobre a Finvia: conta master, uma subconta por cliente, chaves por subconta, remuneração por split e repasse de webhooks aos clientes. Agências digitais e plataformas de tecnologia muitas vezes querem oferecer pagamentos aos clientes com a própria marca: o cliente da agência integra uma vez, vê a marca da agência e não precisa negociar diretamente com um gateway. Esta página mostra como montar essa camada sobre a API da Finvia, com uma subconta para cada cliente, a remuneração da agência separada em cada venda e os avisos de pagamento repassados a cada cliente. > [!TIP] > > Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](/integrar-com-ia). Implementar este caso com um assistente de IA Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md](https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/saques.md](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/split.md](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md) * [https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md) * [https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md](https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar neste projeto o fluxo descrito na página "Agências e plataformas white label" ([https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md](https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md)). Resumo do caso: Agência ou plataforma que monta um gateway próprio sobre a Finvia: conta master, uma subconta por cliente, chaves por subconta, remuneração por split e repasse de webhooks aos clientes. Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## O cenário A **Órbita Digital** é uma agência de Florianópolis que cria e mantém lojas virtuais e sistemas de agendamento para **60 clientes**: lojas de moda, restaurantes, clínicas de estética e escolas de idiomas. A Órbita quer lançar o **Órbita Pay**, uma camada de pagamentos própria: * o sistema de cada cliente fala só com a API do Órbita Pay; * o dinheiro de cada venda entra na conta do cliente; * a Órbita recebe **1,5% do [valor bruto](/glossario)** de cada venda; * cada cliente recebe os avisos de pagamento no sistema dele; * a Órbita vê as taxas de cada cliente para montar a proposta comercial. ## O que a Finvia resolve > [!NOTE] > > **Para o negócio:** com o Connect, a Órbita vira a conta master (MerchantMaster) e cada cliente vira uma subconta (SubMerchant), com cadastro, análise de documentos, chaves de API e saldo próprios. O backend do Órbita Pay cria as cobranças com a chave da subconta do cliente, então o dinheiro entra no saldo do cliente. O campo `split` separa a remuneração da Órbita em cada venda. A Órbita recebe os eventos de cobrança e repassa a cada cliente. A rota de taxas mostra as taxas cadastradas de cada subconta. ## Arquitetura da solução | Necessidade | Recurso | Rota ou guia | | - | - | - | | Habilitar o modelo | Módulo Connect | Contato com o time Finvia | | Conta de cada cliente | Subconta com KYC | `POST /v1/submerchants`, `POST /v1/submerchants/{merchantId}/document` · [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) | | Chaves por cliente | Chaves da subconta | `GET /v1/submerchants/{merchantId}/api-keys` | | Cobranças do cliente | Cobrança com a chave da subconta | `POST /v1/charges` | | Remuneração da agência | `split` para a conta master | [Split](/guias/fast-connect/split) · [Cálculo de split](/guias/fast-connect/calculo-split) | | Avisos ao cliente | Endpoint da conta master com eventos das subcontas, `postbackUrl` e repasse | [Webhooks](/guias/webhooks/visao-geral) · `POST /v1/webhook-endpoints` | | Taxas por cliente | Consulta de taxas e dados cadastrais | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` · [Taxas](/guias/fast-connect/taxas) | | Saque do cliente | Saque da subconta | `POST /v1/submerchants/{merchantId}/payout-requests` · [Saques](/guias/fast-connect/saques) | O desenho abaixo mostra uma venda feita pelo Órbita Pay, do sistema do cliente até o repasse do aviso de pagamento. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB CF(["Cliente final
do Bistrô Maré"]):::comprador SC["Sistema do Bistrô Maré
credencial da Órbita"]:::lojista OP["Backend do Órbita Pay
conta master"]:::lojista COF["Cofre de segredos
chave sk_ de cada cliente"]:::lojista API["Finvia API · Connect"]:::finvia ADQ["Adquirente e bandeiras
cartão em 3x"]:::externo EV[["Eventos das subcontas
charge.* e payout.*"]]:::evento W["Receptor da Órbita
include_submerchants"]:::lojista FL["Fila de repasse
com retentativa própria"]:::lojista CF -->|"1. compra"| SC SC -->|"2. chama a API
do Órbita Pay"| OP OP -->|"3. busca a chave
do cliente"| COF OP ==>|"4. POST /v1/charges
chave da subconta
split 1,5669%"| API API -->|"5. autoriza"| ADQ API -->|"6. publica o evento"| EV EV -.->|"7. entrega"| W W -->|"8. confere o status
e enfileira"| FL FL -.->|"9. repassa no formato
da Órbita"| SC classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 ``` Este segundo desenho mostra a estrutura de contas: a Órbita é a conta master e cada cliente tem a própria subconta. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB FV["Finvia · Connect"]:::finvia OR["Órbita Digital
conta master"]:::lojista S1["Bistrô Maré
subconta"]:::lojista S2["Loja de moda
subconta"]:::lojista S3["Escola de idiomas
subconta"]:::lojista MAIS["...até 60 clientes
cada um com subconta"]:::neutro BK["Conta do Bistrô Maré
Pix na chave CNPJ"]:::externo SO["Saldo da Órbita
parte de cada venda"]:::ok FV -->|"1. habilita o módulo"| OR OR -->|"2. subconta, KYC
e chaves próprias"| S1 OR --> S2 OR --> S3 OR -.-> MAIS S1 -->|"4. saque do saldo
do cliente"| BK S1 -.->|"3. split em
cada venda"| SO S2 -.-> SO S3 -.-> SO classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Todo cliente segue o mesmo desenho do Bistrô Maré: recebe as vendas no próprio saldo e saca por Pix para a chave CNPJ dele. ## Passo a passo **1. Habilite o Connect e defina a configuração padrão** A Finvia habilita o módulo na conta da Órbita. Na criação, cada subconta recebe uma **cópia** das taxas e configurações da conta master vigentes naquele momento. Depois disso, as taxas da subconta são independentes: mudar as taxas da conta master não muda as das subcontas já criadas. Antes de cadastrar o primeiro cliente, alinhe com o time Finvia as taxas e a configuração que a conta master vai ter, porque elas viram o ponto de partida de todas as subcontas. **2. Crie a subconta de cada cliente** Quando a Órbita fecha com um cliente novo, o Bistrô Maré, o backend do Órbita Pay cria a subconta com a chave da conta master. O corpo segue o mesmo formato mostrado em [Marketplace e PSP](/casos-de-uso/marketplace-psp): dados da empresa, `productType`, representante legal, endereço, telefones, conta bancária e `canAccessDashboard`. Com país `BRA`, a API confere o dígito verificador do CNPJ e do CPF do responsável, a UF e o CEP de 8 dígitos, e o `addressLine1` leva o número depois da vírgula (`Av. Paulista, 1000`). Um CNPJ que já existe entre as subcontas da Órbita é recusado com `409`. Com `canAccessDashboard: true`, o cliente ganha acesso ao painel da Finvia e o objeto `user` passa a ser obrigatório. Com `false`, o cliente usa só as telas do Órbita Pay. A decisão é da agência e depende de quanto ela quer centralizar o atendimento. Guarde o `id` da subconta junto do cadastro do cliente no Órbita Pay. **3. Conduza o KYC do cliente** Envie cartão CNPJ, contrato social, documento do responsável (frente e verso) e selfie com documento. Se preferir que o próprio cliente envie os arquivos, emita um token de upload (`POST /v1/submerchants/{merchantId}/document/upload-token`, válido por 300 segundos e de uso único) e deixe o navegador do cliente chamar `POST /v1/document-uploads` com `Authorization: Bearer`. Assim, a chave da agência não sai do servidor. Acompanhe os avisos de status até `active`. Eles vão para o `postbackUrl` informado na criação da subconta (sem ele, para a URL de aviso da conta master, se houver). Quando vier `correcting` ou `rejected`, o motivo está em `rejectionReason`. A correção de dados é feita no painel da Finvia, na gestão de subcontas. **4. Gere e guarde as chaves por cliente** Com a subconta ativa: ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/api-keys" \ -u "$FINVIA_API_KEY:" ``` ```json theme={null} { "publicKey": "pk_2vorkLm4Qp8TzR1sXc7Yb3NdWkE", "secretKey": "sk_2vorkLm4Qp8TzR1sXc7Yb3NdWkE" } ``` A chave secreta do cliente fica **no backend do Órbita Pay**, em um cofre de segredos, associada ao cliente. O sistema do cliente recebe uma credencial da própria Órbita, emitida pela agência. A chave pública pode ir para o front-end do cliente quando ele usar Apple Pay ou 3D Secure; ela não cria cobranças. As duas chaves formam um par: se a secreta for trocada, a pública também muda. > [!WARNING] > > Não entregue a chave secreta da Finvia ao cliente se o modelo é que todas as chamadas passem pela Órbita. Com a chave na mão, o cliente pode criar cobranças sem o `split` da agência. **5. Calcule a remuneração da agência** A Órbita quer 1,5% do valor bruto. O split incide sobre o [valor líquido](/glossario): o valor da venda menos a taxa transacional (fixa mais percentual). Exemplo com números ilustrativos: venda de R\$ 180,00 em 3x, com taxa transacional de 3,99% (índice `2` da linha `tx_spread`) e taxa fixa de R\$ 0,50. | Passo | Conta | Resultado | | - | - | - | | Valor líquido (L) | 180 × (1 − 0,0399) − 0,50 | R\$ 172,318 | | Remuneração desejada | 1,5% × R\$ 180,00 | R\$ 2,70 | | Split a informar (s) | 2,70 ÷ 172,318, arredondado para cima na quarta casa | 1,5669% | | Conferência | 1,5669% × 172,318 | R\$ 2,70 para a Órbita | A taxa de antecipação (2,50% ao mês no exemplo abaixo) não entra nessa conta. Ela só reduz a base quando o cliente antecipa o recebível: nesse caso, o split é recalculado sobre o valor antecipado e a Órbita recebe proporcionalmente menos. A taxa de antecipação é mensal, multiplicada pelo número de meses até o vencimento de cada parcela (mínimo de 1 mês). As taxas reais de cada cliente vêm da rota de taxas, chamada com a chave da conta master: ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/fees-info" \ -u "$FINVIA_API_KEY:" ``` ```json theme={null} { "merchant": { "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE", "legalName": "BISTRO MARE RESTAURANTE LTDA", "companyTaxId": "11222333000181" }, "fees": [ { "feeType": "tx_spread", "paymentMethod": "credit_card", "currencyCode": "BRL", "brand": null, "definition": { "fixed": 0.5, "percentages": [2.99, 3.49, 3.99, 4.49, 4.99, 5.49, 5.99, 6.49, 6.99, 7.49, 7.99, 8.49] } }, { "feeType": "anticipation", "paymentMethod": "credit_card", "currencyCode": "BRL", "brand": null, "definition": { "fixed": 0, "percentages": [2.5] } } ] } ``` Com a chave da conta master, a rota devolve a subconta pedida. Com a chave da própria subconta, ela ignora o `id` e devolve os dados da subconta autenticada. Um `id` que não pertence à Órbita retorna `404` "Subconta não encontrada"; sem o Connect habilitado, `403`. Escolher a linha certa por bandeira e parcela é responsabilidade de quem consome: use a linha da bandeira do cartão quando existir e a linha `brand: null` quando não houver. A rota não traz reserva financeira nem taxa de saque. Lista `fees` vazia, ou sem linha para o método e a moeda, significa subconta sem taxas configuradas: as cobranças dessa combinação são recusadas com `422` `Fees not configured`. Nesse caso, acione o suporte da Finvia. **6. Crie as cobranças pelo Órbita Pay** O sistema do cliente chama a API do Órbita Pay. O backend da Órbita recebe o pedido, calcula o percentual e chama a Finvia com a chave da subconta do cliente: ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$CHAVE_SUBCONTA_BISTRO_MARE:" \ -H "Content-Type: application/json" \ -d '{ "amount": 180, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" } }, "paymentMethod": { "type": "credit_card", "number": "1111222233334444", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 3 }, "items": [ { "title": "Voucher jantar para dois", "type": "digital", "description": "Menu degustação, válido por 90 dias", "unit_price": 180, "quantity": 1 } ], "split": [ { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 1.5669 } ], "metadata": { "orbitaCliente": "bistro-mare", "orbitaPedido": "BM-7781" }, "postbackUrl": "https://pay.orbita.exemplo.com.br/webhooks/finvia/postback" }' ``` O `merchantId` do split é o ID da conta master da Órbita (`36OO3bcGjhPjjF3tzrqOGcmQuKo`). Nos exemplos desta página, `2vorkLm4Qp8TzR1sXc7Yb3NdWkE` é a subconta do Bistrô Maré. O restante do líquido fica com o Bistrô Maré, que é o [originador](/glossario) da venda. A parte da Órbita é repassada quando o recebível do Bistrô Maré é liquidado: no cartão, a cada parcela, em D+30, D+60 e D+90; no Pix, logo após a confirmação do pagamento. **7. Repasse os webhooks a cada cliente** As cobranças pertencem às subcontas dos clientes. Para receber os eventos de todas elas, a Órbita cadastra um endpoint na conta master com a opção de incluir subcontas: ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "url": "https://pay.orbita.exemplo.com.br/webhooks/finvia", "enabled_events": [], "include_submerchants": true }' ``` O corpo vai em snake\_case, e `enabled_events: []` significa todos os eventos. A resposta é `201` sem corpo; para obter o `id` do endpoint, use `GET /v1/webhook-endpoints?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo`. No painel, o mesmo cadastro fica em **Configurações** > **Webhooks**, com a opção de incluir subcontas. O `postbackUrl` de todas as cobranças também aponta para o Órbita Pay, em outra URL. Ao receber um evento, a Órbita identifica o cliente pelo `merchant_id` do evento (ou pelo `metadata`), confirma o status na Finvia e repassa ao endpoint que o cliente cadastrou no Órbita Pay. ```javascript theme={null} app.post('/webhooks/finvia', async (req, res) => { const { id, event, data } = req.body; if (id && (await eventos.jaProcessado(id))) return res.status(200).send('OK'); res.status(200).send('OK'); const cliente = await clientes.porSubconta(data.merchant_id ?? data.merchantId); const cobranca = await finvia.get(`/v1/charges/${data.id}`, cliente.chaveSecreta); // Repasse no formato da Órbita, com o status confirmado na API await filaDeRepasse.enviar(cliente.urlWebhook, { evento: event, pedido: cobranca.metadata?.orbitaPedido, status: cobranca.status, valor: cobranca.amount, }); if (id) await eventos.marcarProcessado(id); }); ``` | Canal da Finvia | O que chega | Observação | | - | - | - | | Endpoint da conta master com `include_submerchants: true` | Eventos de cobrança, de assinatura e de saque das subcontas, como `charge.paid`, `charge.refunded`, `charge.blocked`, `payout.approved` e `payout.rejected` | Envelope padrão; o `merchant_id` (ou `merchantId`, nos saques) indica a subconta | | `postbackUrl` da cobrança | Os mesmos eventos de cobrança, mais o `charge.updated` legado | `charge.updated` (chargeback formalizado, recusa ou falha informada depois pela adquirente, Pix expirado, fim do 3DS, bloqueio, pré-chargeback) só chega por aqui, sem `id` de evento e em camelCase | | Aviso de status da subconta | `pre_approved`, `correcting`, `active`, `rejected`, `blocked` | Vai ao `postbackUrl` do cadastro da subconta; payload sem envelope; responda com 2xx | > [!TIP] > > **Para o desenvolvedor:** responda à Finvia com `200` antes de repassar ao cliente, e faça o repasse por uma fila com retentativa própria. Se o endpoint do cliente estiver fora do ar, a fila da Órbita tenta de novo, sem depender de uma nova entrega da Finvia. Como o `charge.updated` não tem `id`, use o `data.id` da cobrança mais o `status` e o `updatedAt` para deduplicar. **8. Ofereça saque ao cliente** Cada cliente saca o próprio saldo por Pix para a chave CNPJ da subconta, com valor em reais e mínimo de R\$ 1,00. A Órbita pede o saque com a chave secreta da conta master: ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/payout-requests" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 1200 }' ``` O saque nasce `pending`, passa por aprovação da Finvia e termina `approved` ou `rejected`. Os avisos `payout.approved` e `payout.rejected` chegam ao endpoint da conta master com a opção de incluir subcontas, com os valores em texto decimal (`"1200.00000000"`). Confirme o status pela listagem `GET /v1/payout-requests?merchantId=2vorkLm4Qp8TzR1sXc7Yb3NdWkE` antes de avisar o cliente. Oriente cada cliente a cadastrar o CNPJ como chave Pix em uma conta bancária da empresa antes do primeiro saque. ## Regras e cuidados > [!WARNING] > > **Uma chave por cliente, sempre a certa.** Cobrança criada com a chave da conta master fica no saldo da Órbita. Cobrança criada com a chave de outro cliente fica no saldo do cliente errado. Valide o mapeamento cliente → chave antes de cada chamada. > [!WARNING] > > **Valores em reais** em cobrança, split e saque. `"amount": 180` é R\$ 180,00. * **Mesmo grupo.** As contas do `split` precisam pertencer ao mesmo [grupo Connect](/glossario) (a conta master e as subcontas dela). A soma dos percentuais não passa de 100%. * **Split da requisição prevalece.** O `split` enviado na cobrança vale para aquela venda e prevalece sobre a regra padrão de split da conta. * **Assinaturas sem split.** Se um cliente cobrar mensalidades por assinatura, essas cobranças recorrentes não recebem split e a remuneração da Órbita não sai automaticamente. * **Webhooks sem assinatura.** Os eventos não têm assinatura HMAC ([Webhooks](/guias/webhooks/visao-geral#regras-de-negócio)): confirme o status na API antes de repassar ao cliente um evento que libera produto ou serviço. * **Saques pela listagem.** Confirme o status de cada saque em `GET /v1/payout-requests` antes de avisar o cliente. * **Homologação por funcionalidade.** Cada funcionalidade que a Órbita oferece (cartão, Pix, Apple Pay, split, subcontas, saques) tem cenários próprios no roteiro. O roteiro é uma etapa recomendada, acompanhada pelo suporte da Finvia; a API não bloqueia a produção até a homologação. ## Variações do caso > [accordion] E se a agência preferir cobrar uma mensalidade fixa? > > Remova o `split` das cobranças dos clientes e cobre a mensalidade da agência como uma assinatura na conta master, com o cliente da agência como pagador. O desenho está em [SaaS por assinatura](/casos-de-uso/saas-assinaturas). > [accordion] E se um cliente da agência tiver vendedores próprios? > > Subconta e conta master formam um único nível no Connect. Se o cliente for um marketplace com vendedores, os vendedores podem ser subcontas no mesmo grupo da Órbita, e a venda pode separar a parte do marketplace (subconta para subconta) e a parte da Órbita (subconta para conta master) no mesmo `split`. A soma dos percentuais continua limitada a 100%. > [accordion] E se um cliente quiser Apple Pay no site dele? > > O domínio do checkout precisa ser registrado com a chave secreta **da subconta do cliente** (`POST /v1/apple-pay/domains`). Registrar o primeiro domínio ativa o Apple Pay na subconta, e o registro vale para teste e produção. Plataformas que servem várias lojas no mesmo hostname registram esse hostname uma vez para cada merchant. A validação de sessão no navegador usa a chave pública da subconta. Detalhes no [guia de Apple Pay](/guias/cobrancas/apple-pay). > [accordion] E se a agência quiser dar ao cliente acesso direto ao painel? > > Crie a subconta com `canAccessDashboard: true` e o objeto `user` (nome, e-mail e telefone no formato E.164). O cliente passa a ver as próprias movimentações no painel da Finvia. ## Checklist de implementação * [ ] Connect habilitado e configuração padrão da conta master alinhada com a Finvia * [ ] Criação de subconta por cliente, com KYC completo * [ ] Token de upload para o cliente enviar documentos sem expor a chave da agência * [ ] Tratamento dos avisos de status das subcontas * [ ] Chaves secretas dos clientes em cofre de segredos, no backend da agência * [ ] Mapeamento cliente → subconta → chave validado antes de cada cobrança * [ ] Percentual do split calculado por venda com as taxas de `fees-info` * [ ] `postbackUrl` da agência em todas as cobranças * [ ] Repasse de eventos aos clientes por fila própria, com status confirmado na API * [ ] Deduplicação por `id` de evento e, no `charge.updated`, por cobrança + status + data * [ ] Endpoint da conta master com `include_submerchants: true` para cobranças e saques das subcontas * [ ] Cenários de homologação de cada funcionalidade oferecida aos clientes ## Como homologar | Funcionalidade | Cenários | | - | - | | Subcontas | FC-01 a FC-08 | | Remuneração por split | SPL-01 a SPL-06 | | Cobranças | CHG-01 a CHG-10, conforme os métodos oferecidos | | Apple Pay, se oferecido | AP-01 a AP-06 | Cada cenário pede evidência (requisição, resposta, `id` e registro de webhook), enviada ao suporte da Finvia, que acompanha a homologação. O saque (FC-07) não roda com a chave de teste, que recebe `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. Detalhes no [roteiro de homologação](/homologacao/roteiro) e no [checklist de go-live](/homologacao/checklist-go-live). ## Veja também > [card] [Connect](/guias/fast-connect/visao-geral) > > Conta master, subcontas e cópia das configurações na criação. > [card] [Chaves de API da subconta](/referencia/fast-connect/chaves-de-api) > > Referência da rota de chaves. > [card] [Taxas e dados da subconta](/referencia/fast-connect/taxas-e-dados) > > Referência da rota `fees-info`. > [card] [Webhooks](/guias/webhooks/visao-geral) > > Canais, envelopes e retentativas. # Conceitos essenciais Source: https://docs.fastpaybrasil.com/conceitos Os termos e objetos que aparecem em toda a API, explicados para quem programa e para quem decide. Esta página explica as peças que formam a API da Finvia: quem vende, quem paga, o que é cobrado, como o dinheiro se move e como o seu sistema fica sabendo de cada mudança. Cada conceito traz uma explicação em linguagem de negócio e, quando ajuda, o nome técnico que aparece nos campos e nas rotas. Para definições curtas em ordem alfabética, use o [Glossário](/glossario). O desenho abaixo mostra como os principais objetos da API se relacionam. Cada um deles é explicado nas seções seguintes. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB M["Sua conta (merchant)
no Connect, a conta master"]:::lojista SUB["Subcontas (Connect)
um vendedor cada"]:::lojista CLI(["Cliente
customer"]):::comprador PLAN["Plano
preço e periodicidade"]:::neutro CARD["Cartão salvo
id do cofre = cardTokenId"]:::neutro ASS["Assinatura
cliente + plano + cartão"]:::neutro CHG["Cobrança (charge)
items · paymentMethod"]:::finvia WH[["Webhooks
charge.* · subscription.*"]]:::evento WAL["Carteira (wallet)
saldo por moeda"]:::neutro PAY["Saque (payout)
Pix para a chave CNPJ"]:::neutro M -->|"cria e gerencia"| SUB M -->|"cadastra"| CLI M -->|"cria"| PLAN CLI -->|"guarda no cofre"| CARD CLI --> ASS PLAN --> ASS CARD --> ASS M -->|"POST /v1/charges"| CHG CLI -->|"paga"| CHG CARD -.->|"recompra com CVV"| CHG ASS -->|"cobra a cada ciclo"| CHG CHG -.->|"split opcional"| SUB CHG -->|"cada mudança"| WH ASS -->|"cada mudança"| WH CHG -->|"valor liquidado"| WAL WAL -->|"sacar"| PAY classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ## Quem participa ### Merchant (lojista) O **merchant** é a empresa cliente da Finvia que vende e recebe. É a sua empresa. Toda cobrança, cliente, cartão salvo e plano pertence a um merchant, e o merchant é identificado pela chave usada na requisição. Em respostas da API, o campo `merchantId` indica a qual conta um objeto pertence. ### Conta master e subconta (Connect) O **Connect** é o módulo da Finvia para marketplaces e plataformas que atendem vários vendedores. Ele é habilitado pela Finvia na sua conta e cria uma hierarquia de duas camadas: | Papel | Nome técnico | O que faz | | - | - | - | | **Conta master** | MerchantMaster | A plataforma. Cria e gerencia as subcontas, define regras de split e acompanha os saques | | **Subconta** | SubMerchant | Cada vendedor da plataforma. Tem CNPJ, dados bancários, chaves de API e saldo próprios | Na criação, a subconta recebe uma **cópia das taxas e configurações** vigentes da conta master. Depois disso, as taxas da subconta são independentes: alterar as taxas da master não muda as das subcontas já criadas. Antes de vender, ela passa por análise cadastral (KYC, a verificação de identidade da empresa e dos sócios) e só opera depois de aprovada, com status `active`. > [!NOTE] > > **Para o negócio:** com o Connect, cada venda fica registrada na conta do vendedor que vendeu, e a comissão da plataforma é separada automaticamente pelo split. Isso dá rastreabilidade por vendedor e evita repasses manuais. ### Cliente (customer) O **cliente** é quem paga: a pessoa ou empresa que compra do merchant. Na API, é o objeto `customer`. Há duas formas de informar o cliente em uma cobrança: * **Cadastro prévio:** você cria o cliente com [`POST /v1/customers`](/referencia/clientes/criar) (`name`, `email`, `documentId` e `documentType` obrigatórios) e depois envia só o `customer.id` na cobrança. * **Cadastro junto com a cobrança:** você envia `name` e `email` (ou `phone`) dentro da cobrança, e a API cria ou localiza o cliente. O cadastro prévio é o caminho natural quando o mesmo cliente volta a comprar, guarda cartão ou assina um plano. Depois de criado, o documento do cliente não pode ser alterado: [`PUT /v1/customers/{id}`](/referencia/clientes/atualizar) aceita só `name`, `email` e `phoneNumber`. ## O que é cobrado ### Cobrança (charge) A **cobrança** (charge) é o pedido de pagamento: quanto cobrar, de quem, pelo quê e por qual meio. É o objeto central da API, criado em [`POST /v1/charges`](/referencia/cobrancas/criar). Ela nasce com um `id` único, que é a chave para consultar, estornar e conciliar a cobrança com os webhooks. Campos obrigatórios na criação: `amount`, `currency`, `customer`, `paymentMethod` e `items`. O valor vai em reais: `"amount": 10` significa R\$ 10,00 e `"amount": 99.9` significa R\$ 99,90. O mínimo é `1`. ### Item Cada cobrança traz a lista `items`, com o que está sendo vendido. Todos os campos do item são obrigatórios: `title`, `type`, `description`, `unit_price` e `quantity`. O `type` do item é `physical` (produto físico) ou `digital` (produto digital ou serviço). Se algum item da cobrança for `physical`, o endereço de entrega (`shippingAddress`) é obrigatório, com `postalCode`, `addressLine1`, `city`, `state` e `country` (`addressLine2` e `neighborhood` são opcionais). Sem ele, a API responde `400` e não cria a cobrança. ### Forma de pagamento A Finvia aceita dois meios de pagamento: **cartão de crédito** (digitado, salvo no cofre ou via Apple Pay) e **Pix**. A forma de pagamento vai no objeto `paymentMethod` da cobrança e é identificada pelo campo `type`: | Forma | `type` | Como o cliente paga | Quando o resultado sai | | - | - | - | - | | Pix | `pix` | Lê o QR Code ou cola o código no app do banco | Depois, quando o cliente paga (aviso por webhook) | | Cartão de crédito | `credit_card` | Digita os dados do cartão | Na própria resposta da criação | | Cartão salvo | `credit_card` com `cardTokenId` | Informa só o CVV | Na própria resposta da criação | | Apple Pay | `credit_card` com `wallet` | Autoriza no iPhone, Mac ou Apple Watch | Na própria resposta da criação | A rota [`GET /v1/payment-methods`](/referencia/meios-de-pagamento/listar) lista os meios de pagamento habilitados para a sua conta. ### Status O **status** diz em que ponto da vida a cobrança está. Ele muda ao longo do tempo, e o seu sistema acompanha essas mudanças pelos webhooks ou consultando a cobrança. | Status | Significado resumido | | - | - | | `pending` | Aguardando pagamento | | `paid` | Pago | | `refused` | Recusado pelo processador | | `failed` | Falha no processamento | | `refunded` | Estornado | | `in_analysis` | Em análise antifraude | | `authentication_required` | Aguardando autenticação do comprador (3D Secure) | | `pre_chargeback` | Alerta de contestação recebido antes do chargeback formal | | `chargeback` | Chargeback formalizado | A tabela completa, com o que fazer em cada status, está em [Status de cobrança](/anexos/status-de-cobranca). O bloqueio de uma cobrança em disputa não é um status: a cobrança continua `paid` e passa a ter `isBlocked: true` (veja [Bloqueio](#bloqueio)). > [!NOTE] > > **Para o negócio:** a regra mais segura para liberar um pedido, enviar um produto ou dar acesso a um curso é esperar o status `paid`. `pending` e `in_analysis` ainda não significam dinheiro recebido. ## Ciclo de vida de uma cobrança ### Cobrança Pix **1. Seu sistema cria a cobrança** Você chama `POST /v1/charges` com `paymentMethod.type` igual a `pix` e a validade do QR Code (`expirationInDays` ou `expirationInSeconds`, mínimo de 900 segundos, ou seja, 15 minutos). **2. A API devolve o QR Code** A resposta `201` traz `status` `pending` e, em `paymentDetails`, o código copia e cola (`copyPaste`) e a imagem do QR Code (`qrCodeBase64`). Seu checkout mostra essas informações ao cliente. **3. A Finvia avisa que a cobrança foi criada** Os webhooks `charge.created` e `charge.pending` chegam aos endpoints cadastrados no painel e à `postbackUrl` da cobrança, se informada. **4. O cliente paga no app do banco** O pagamento é feito fora do seu sistema, no aplicativo bancário do cliente. **5. A Finvia confirma o pagamento** O webhook `charge.paid` chega com `status` `paid` e a data em `paid_at`. A partir daí, você pode liberar o pedido. No sandbox, o Pix de teste vira `paid` sozinho, cerca de 5 segundos depois da criação. **6. Pós-venda, se houver** Se for preciso devolver o dinheiro, um [estorno](/guias/estorno) leva a cobrança a `refunded` e dispara `charge.refunded`. Se o pagamento for contestado, a cobrança pode ser [bloqueada](/guias/bloqueio-chargeback-med). ### Cobrança com cartão de crédito **1. Seu sistema cria a cobrança** Você chama `POST /v1/charges` com `paymentMethod.type` igual a `credit_card`, os dados do cartão (ou o `cardTokenId` de um cartão salvo, ou o `wallet` do Apple Pay) e o número de parcelas (`installments`, até 12). **2. Autenticação 3D Secure, quando aplicável** Com o 3D Secure gerenciado (`threeDSMode` igual a `managed`), quando a política 3DS da conta dispara e o banco emissor pede verificação ou desafio, a cobrança nasce com `authentication_required` e traz a `authenticationUrl`, para onde o comprador é levado. A própria página dessa URL conduz a autenticação e retoma a cobrança, que só é processada depois disso. Na autenticação sem atrito, a resposta já traz o status final. **3. A resposta traz o resultado** Na resposta `201`, o `status` já indica aprovação (`paid`), recusa (`refused`) ou falha (`failed`). Em recusas, o campo `reason` explica o motivo, e o checkout pode oferecer outra forma de pagamento em seguida. **4. A Finvia notifica o resultado** O webhook `charge.paid` (aprovação), `charge.refused` (recusa) ou `charge.failed` (falha) chega aos endpoints cadastrados e à `postbackUrl`. A resposta síncrona continua sendo a fonte principal; o webhook é complementar. **5. Pós-venda, se houver** Estorno total (`refunded`), alerta de contestação (`pre_chargeback`) ou chargeback (`chargeback`), cada um com sua notificação. ## Como o seu sistema fica sabendo ### Webhook e postback Um **webhook** é uma notificação que a Finvia envia ao seu servidor, por uma requisição HTTP POST com corpo em JSON, quando algo acontece. Assim você não precisa consultar a API o tempo todo para saber se uma cobrança foi paga. Existem dois canais para eventos de cobrança, e eles se complementam: | Canal | Onde é configurado | O que recebe | | - | - | - | | **Webhook** (endpoint cadastrado) | No painel, em **Configurações > Webhooks** da conta selecionada, ou pela API em [`POST /v1/webhook-endpoints`](/referencia/webhooks/criar-endpoint) | Eventos de todas as cobranças e assinaturas da conta (`charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback`, `charge.blocked` e `subscription.*`) e, nas subcontas, os eventos de saque | | **Postback** | No campo `postbackUrl` de cada cobrança | Os mesmos eventos de cobrança, só daquela cobrança, mais o `charge.updated` legado, que só existe neste canal | O webhook de cobrança tem um envelope com `id` (identificador do evento), `event` (nome do evento), `livemode` (`false` em cobranças de teste) e `data` (a cobrança). Os mesmos endpoints recebem eventos de teste e de produção: separe-os por `livemode`. O `charge.updated` tem formato próprio, sem `id` e sem `livemode`. Detalhes em [Webhooks](/guias/webhooks/visao-geral) e no [Catálogo de eventos](/anexos/catalogo-de-eventos). > [!WARNING] > > Os webhooks não trazem assinatura HMAC: antes de uma ação crítica, confirme o estado com [`GET /v1/charges/{id}`](/referencia/cobrancas/consultar) (veja [Webhooks](/guias/webhooks/visao-geral#regras-de-negócio)). Use sempre HTTPS no seu endpoint. ## Depois da venda ### Estorno O **estorno** devolve ao cliente o valor de uma cobrança paga. Na API ele é sempre **total**: estorno parcial não é suportado. Só cobranças com `status` `paid` podem ser estornadas (as demais recebem `404`), e cada cobrança aceita um único estorno (um segundo pedido recebe `422`). A rota é [`POST /v1/refunds`](/referencia/cobrancas/estornar), com `chargeId` e `reason`. Funciona para Pix e cartão de crédito. ### Chargeback, pré-chargeback e MED * **Chargeback** é a contestação de uma compra com cartão, aberta pelo banco emissor do cartão por meio da bandeira. A disputa chega à Finvia pela adquirente, e a decisão final é do emissor ou da bandeira. Se a contestação prevalece, o valor volta ao portador e a cobrança fica `chargeback`. * **Pré-chargeback** é um alerta recebido antes de o chargeback ser formalizado. A cobrança vai para `pre_chargeback` e o evento `charge.pre_chargeback` é enviado. O campo `chargebackAlertRefunded` (no webhook, `chargeback_alert_refunded`) diz se o valor já foi devolvido ao portador (`true`) ou se a disputa segue aberta sem estorno (`false`). * **MED** (Mecanismo Especial de Devolução) é o mecanismo do Pix, definido pelo Banco Central, que permite à instituição de quem pagou pedir a devolução de um Pix quando há fundada suspeita de fraude ou falha operacional. A contestação é analisada pela instituição de quem recebeu. Durante a análise, o valor fica bloqueado; se a contestação for aceita, ele é devolvido ao pagador. O MED existe só no Pix. O MED é diferente do **bloqueio cautelar**, outra ferramenta do Pix: uma retenção preventiva e curta, feita pela instituição de quem recebeu quando suspeita de fraude. Na API da Finvia, os dois aparecem do mesmo jeito, como bloqueio da cobrança. ### Bloqueio Quando há um MED, um chargeback em análise ou outra suspeita, a equipe Finvia pode **bloquear** uma cobrança `paid`. O bloqueio não chega automaticamente do banco: é aplicado pela Finvia. Na API, não existe status nem evento chamado MED. O que você vê é: * a cobrança continua com `status` `paid` e passa a ter `isBlocked: true`, `blockedAt` e `blockedReason` (texto livre, que pode vir vazio); * o evento `charge.blocked` vai aos endpoints e à `postbackUrl` da cobrança, e a `postbackUrl` recebe também o `charge.updated` legado; * o valor já liquidado da venda sai do saldo disponível e vai para o saldo bloqueado; * `GET /v1/charges?status=blocked` lista as cobranças bloqueadas. A defesa não é feita pela API. O alerta de chargeback ou MED chega por e-mail à conta (no Connect, à conta master). Você responde a esse e-mail com as evidências da venda (comprovante de entrega, nota fiscal, conversa com o cliente), dentro do prazo indicado nele. Dúvidas, pelo suporte. Os desfechos possíveis: | Desfecho | O que a API mostra | | - | - | | Bloqueio retirado | `isBlocked: false`. Hoje, a liberação não gera webhook: consulte a cobrança. Use `isBlocked`, porque `blockedAt` continua preenchido | | Contestação aceita no Pix | Estorno: `status` `refunded` e evento `charge.refunded` | | Chargeback perdido no cartão | `status` `chargeback`, informado pela adquirente. Chega à `postbackUrl` como `charge.updated` com `status: "chargeback"` e, quando o valor é revertido do saldo, também como `charge.refunded` | Detalhes em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ## Cartões e recorrência ### Cartão salvo (cofre e token) O **cofre de cartões** guarda o cartão do cliente de forma segura na Finvia. Ao registrar um cartão com [`POST /v1/cards`](/referencia/cartoes/registrar), você recebe um `id` (o token do cartão) e passa a usar esse identificador no lugar do número. O cartão pertence ao merchant da chave que o registrou e não pode ser usado por outro merchant ou subconta. Regras que mudam o desenho do produto: * Para registrar, o cliente precisa ter **e-mail** e **CPF ou CNPJ**. Outros documentos, como passaporte, são recusados. * Com o processador atual, o cartão já nasce `active`. Não há transação de teste nem etapa de ativação. * Em uma cobrança avulsa com cartão salvo (`cardTokenId`), o **CVV do comprador é obrigatório toda vez**. Para cobrar sem o comprador presente, use assinaturas. * O cofre é o mesmo para teste e produção: um `cardTokenId` criado com a chave de teste cobra de verdade se for usado com a chave de produção. ### Plano e assinatura | Conceito | O que é | Exemplo | | - | - | - | | **Plano** | O modelo da cobrança recorrente: nome, preço, moeda, periodicidade e, opcionalmente, período de teste | "Plano Premium Mensal, R\$ 99,90 por mês, 14 dias grátis" | | **Assinatura** | O vínculo de um cliente a um plano, com um cartão | "Maria Souza assina o Plano Premium desde 15/01" | A periodicidade do plano (`recurrenceType`) pode ser `weekly`, `biweekly`, `monthly` ou `custom`. Editar um plano não altera assinaturas existentes: preço, moeda e periodicidade ficam congelados no momento da contratação. Uma assinatura aceita só alteração de `metadata`. Para trocar cartão ou plano, cancele e crie outra. Detalhes em [Assinaturas](/guias/assinaturas/visao-geral). > [!NOTE] > > **Para o negócio:** cancelamentos em até 7 dias da criação da assinatura são tratados como arrependimento e estornam automaticamente todas as cobranças pagas. Depois disso, o cancelamento é regular: as cobranças param imediatamente, sem estorno, e a sua plataforma controla o acesso até o fim do período pago. ## Dinheiro em movimento O desenho abaixo mostra o caminho do dinheiro, da cobrança paga até o saque na conta bancária. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB PAID(["Cobrança paga
status paid"]):::ok LIQ["Recebível liquidado
Pix: no mesmo dia
cartão: D+30, D+60..."]:::finvia SO["Saldo disponível
do originador"]:::lojista SR["Saldo disponível
do recebedor do split"]:::lojista SAQ["Saque pedido · pending
valor bruto sai do
saldo disponível"]:::alerta OK["approved
Pix do valor líquido
para a chave CNPJ"]:::ok REJ["rejected
o valor volta ao
saldo disponível"]:::erro PAID -->|"1. desconta a
taxa transacional"| LIQ LIQ -->|"2. a cada parcela"| SO SO -->|"3. split: percentual
sobre o valor líquido"| SR SO -->|"4. saque"| SAQ SR -->|"4. saque"| SAQ SAQ -->|"aprovado"| OK SAQ -->|"recusado"| REJ classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` O split só acontece entre contas do mesmo grupo Connect. As regras de cada etapa estão nas seções abaixo. ### Split (divisão de valores) O **split** divide o valor de uma cobrança entre contas do mesmo [grupo Connect](/glossario) (a conta master e as subcontas dela). Você informa no campo `split` da cobrança quais contas recebem e qual percentual de cada uma. Sem `split`, vale a regra de split padrão da conta para aquela moeda e método, se houver (em subconta sem regra própria, vale a da master). * A soma dos percentuais não pode passar de 100%. O que sobra fica com o [originador](/glossario), a conta que criou a cobrança. * Todas as contas precisam pertencer ao mesmo grupo Connect. * Por padrão, o percentual é aplicado sobre o **[valor líquido](/glossario)**, depois da taxa transacional. O uso do valor bruto é configurado pela Finvia, sob consulta. * O valor de cada participante é calculado na criação da cobrança e repassado a cada parcela, quando o recebível do originador é liquidado: no cartão, cada parcela em D+30, D+60 e assim por diante; no Pix, no mesmo dia, logo após a confirmação do pagamento. O repasse sai do saldo disponível do originador e entra no saldo disponível do recebedor. * As cobranças recorrentes de assinatura não recebem split. > [!NOTE] > > **Para o negócio:** se a sua plataforma cobra uma comissão de 10% sobre o valor bruto da venda, o percentual de split precisa ser maior que 10% para entregar o mesmo valor, porque a base é o líquido. O cálculo está em [Cálculo de split](/guias/fast-connect/calculo-split). ### Saldo e carteira (wallet) A **carteira** (wallet) mostra o saldo da conta por moeda, em três partes: `available` (disponível), `pending` (a liberar) e `reserved` (reservado). O campo `isWithdrawalEnabled` diz se saques estão habilitados naquela moeda. A rota é [`GET /v1/wallets`](/referencia/carteiras/listar). ### Saque (payout) O **saque** (payout) transfere saldo para fora da Finvia, sempre por **Pix** para a chave CNPJ da conta que saca (o mesmo CNPJ do cadastro). Antes de sacar, cadastre esse CNPJ como chave Pix em uma conta bancária da empresa. As rotas de saque usam Basic com a chave secreta, e não existe saque no Modo Teste: com a chave de teste, a criação responde `403`. | Saque | Rota | Como funciona | | - | - | - | | Da própria conta | [`POST /v1/payout-requests`](/referencia/saques/criar) | Corpo com `merchantId`, `amount` em reais, `currency` `BRL` e `externalAccountDetails` `{ "type": "pix" }`. Responde `201` sem corpo; o `id` se obtém na listagem. Não gera webhook | | De subconta (Connect) | [`POST /v1/submerchants/{merchantId}/payout-requests`](/referencia/fast-connect/criar-saque) | Corpo com `amount` em reais (mínimo R\$ 1,00). Responde com o `id`. Sempre passa por aprovação manual e gera os webhooks `payout.approved` e `payout.rejected` | A taxa de saque é descontada do valor (`netAmount` é o líquido). Os status são: | Status | Significado | | - | - | | `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda decisão | | `approved` | Aprovado (pela operação ou por aprovação automática) e enviado para pagamento | | `rejected` | Recusado. O valor volta ao saldo disponível, e o motivo fica em `rejectionReason` | O acompanhamento é pela listagem [`GET /v1/payout-requests`](/referencia/saques/listar). ## Ambientes e chaves A Finvia usa o mesmo endereço para testes e produção: `https://api-global.fastpaybrasil.com`. O ambiente é definido pela chave. | Chave | Prefixo | Uso | | - | - | - | | Chave secreta de produção | `sk_` | No servidor, para operações reais | | Chave secreta de teste | `sk_test_` | No servidor, no sandbox | | Chave pública | `pk_` (`pk_test_` em teste) | No navegador, só nas rotas que pedem por ela (Apple Pay e 3D Secure) | A chave age com as permissões do usuário que a gerou. No Modo Teste, toda cobrança via `POST /v1/charges` é simulada, inclusive com cartão salvo. O cadastro de cartão registra o cartão de verdade (sem cobrar) e as **assinaturas cobram de verdade** mesmo com a chave de teste. Como gerar e usar as chaves: [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes). ## Veja também > [card] [Glossário](/glossario) > > Definições curtas de termos de pagamentos e da API. > [card] [Mapa da API](/mapa-da-api) > > Todas as rotas em uma página. > [card] [Sua primeira cobrança](/primeiros-passos/primeira-cobranca) > > Coloque os conceitos em prática no sandbox. > [card] [Status de cobrança](/anexos/status-de-cobranca) > > Cada status, quando acontece e o que fazer. # Glossário Source: https://docs.fastpaybrasil.com/glossario Termos de pagamentos e da API da Finvia em ordem alfabética, com definições curtas e as regras que a API aplica a cada um. Definições curtas para consulta rápida. Quando um termo tem uma regra específica na API da Finvia, ela aparece na coluna "Na API da Finvia". Para uma explicação mais longa dos principais objetos, veja [Conceitos essenciais](/conceitos). ## A a C | Termo | Definição | Na API da Finvia | | - | - | - | | **3D Secure (3DS)** | Protocolo das bandeiras de cartão que autentica o comprador junto ao banco emissor antes da compra online, por exemplo com uma confirmação no app do banco. | Três formatos: gerenciado (`threeDSMode` igual a `managed`), pelo SDK de segurança ou pelas rotas `/v1/three-ds/*`. Veja [3D Secure](/guias/3d-secure/visao-geral). | | **ACS** | Access Control Server: o sistema do banco emissor que conduz a autenticação 3DS e apresenta o desafio ao comprador. | Aparece no campo `acsTransactionId` do resultado 3DS. | | **Adquirente** | Empresa que processa as transações de cartão do lojista junto às bandeiras e liquida os valores. Também chamada de credenciadora. | | | **Antecipação** | Recebimento antes do prazo original de valores de vendas no cartão, mediante uma taxa. | As taxas de antecipação da subconta aparecem com `feeType` `anticipation` em `GET /v1/fast-connect/sub-accounts/{id}/fees-info`. O webhook de cobrança traz `anticipation_fee_estimated`. | | **API key** | Ver **Chave secreta** e **Chave pública**. | | | **Assinatura** | Vínculo de um cliente a um plano, com cobrança automática a cada ciclo. | Rotas em `/v1/subscriptions`. Status: `pending_activation`, `active`, `cancelled`, `expired`. As cobranças de assinatura são reais mesmo com a chave de teste. | | **Bandeira** | Rede do cartão, como Visa, Mastercard e Elo. Define regras de aceitação, contestação e autenticação. | O campo `brand` do cartão salvo traz a bandeira (ex.: `visa`). | | **Base64** | Forma de representar bytes como texto usando 64 caracteres. Usada para transportar dados binários ou credenciais em cabeçalhos HTTP. | O cabeçalho de autenticação é o Base64 de `sua_chave:`. Para conferir, decodifique e veja se termina em `:`. O QR Code do Pix vem como imagem em Base64 em `qrCodeBase64`. | | **Basic Auth** | Esquema de autenticação HTTP em que usuário e senha vão no cabeçalho `Authorization`, codificados em Base64. | A chave secreta vai como usuário e a senha fica vazia: `Authorization: Basic base64(sk_...:)`. | | **BIN / first six** | Os primeiros dígitos do cartão, que identificam o emissor e o produto. | A API devolve os seis primeiros em `firstSix`, na resposta da cobrança e no `payment_method` de cartão do webhook. | | **Bloqueio cautelar** | Ferramenta do Pix em que a instituição de quem recebeu retém o valor de forma preventiva e curta quando suspeita de fraude. É diferente do MED. | Na API, aparece como bloqueio da cobrança (`isBlocked: true`), do mesmo jeito que o MED. Veja [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). | | **BR Code** | Padrão do código do Pix, no formato EMV. | É o conteúdo do campo `copyPaste`. | | **CAVV** | Cardholder Authentication Verification Value: o criptograma que comprova a autenticação 3DS. | Campo `cryptogram` do objeto `threeDS`, em Base64. Obrigatório para autenticação bem-sucedida. | | **Challenge (desafio)** | Etapa do 3DS em que o comprador precisa agir para se autenticar, por exemplo digitando um código ou confirmando no app do banco. | Status `requires_challenge` e URL em `challengeUrl` nas rotas de 3DS. | | **Chargeback** | Contestação de uma compra com cartão, aberta pelo banco emissor por meio da bandeira. Chega à Finvia pela adquirente. Se prevalece, o valor é devolvido ao portador. | Status `chargeback` (formalizado), avisado na `postbackUrl` por `charge.updated` e, quando o valor é revertido do saldo, também por `charge.refunded`. O alerta chega por e-mail à conta (no Connect, à conta master) e a defesa é enviada em resposta a esse e-mail, dentro do prazo indicado nele. Não há envio de defesa pela API. Veja [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). | | **Chave pública** | Credencial que pode ficar no navegador ou no app, usada só nas rotas que pedem por ela. | Prefixo `pk_` (`pk_test_` em teste). Usada no 3D Secure, na validação de sessão do Apple Pay e na inicialização do SDK. Obtida no painel, em **Configurações > Chave de API**. | | **Chave secreta** | Credencial que identifica a sua empresa nas chamadas à API. Deve ficar só no servidor. | Prefixo `sk_` em produção e `sk_test_` no sandbox. Age com as permissões do usuário que a gerou. | | **Cliente (customer)** | Quem paga a cobrança. | Objeto `customer`. Cadastro em `POST /v1/customers`, com `name`, `email`, `documentId` e `documentType` obrigatórios. | | **Cobrança (charge)** | Pedido de pagamento com valor, cliente, itens e forma de pagamento. | Criada em `POST /v1/charges`. O valor vai em reais (`10` = R\$ 10,00), com mínimo `1`. | | **Cofre de cartões** | Armazenamento seguro de cartões para uso futuro, sem que o lojista guarde o número. | `POST /v1/cards` devolve o `id` do cartão salvo. O cofre é o mesmo para teste e produção. Veja [Cofre de cartões](/guias/cofre-de-cartoes). | | **Connect** | Módulo da Finvia para marketplaces: conta master, subcontas, split e saques. | Habilitado pela Finvia na conta. Veja [Connect](/guias/fast-connect/visao-geral). | | **Conta master** | No Connect, a conta da plataforma que cria e gerencia subcontas. Também chamada de MerchantMaster. | | | **CVV** | Código de segurança impresso no cartão. | Obrigatório em toda cobrança avulsa com cartão, inclusive com cartão salvo (`cardTokenId`). Mínimo de 3 caracteres. | ## D a M | Termo | Definição | Na API da Finvia | | - | - | - | | **Data URI** | Forma de embutir um arquivo dentro de um texto, começando com `data:` e o tipo do arquivo. | `qrCodeBase64` vem como `data:image/png;base64,...` e pode ir direto no `src` de uma imagem. | | **Directory Server (DS)** | Servidor da bandeira que conecta o lojista ao banco emissor no fluxo 3DS. | Campo `directoryServerTransactionId`. | | **ECI** | Electronic Commerce Indicator: código que indica o resultado da autenticação de uma transação online. | Campo `eci`. Valores comuns: `05` (autenticado), `06` (tentativa), `07` (não autenticado). | | **End-to-end ID** | Identificador único de uma transação Pix, gerado pelo arranjo Pix e usado para rastreio entre bancos. | Campo `endToEndId` em `paymentDetails`. | | **Estorno** | Devolução ao cliente do valor de uma cobrança paga. | Sempre total, em `POST /v1/refunds`. Só para cobranças `paid` e um por cobrança. Veja [Estorno](/guias/estorno). | | **Grupo Connect** | Conjunto formado por uma conta master e as subcontas vinculadas a ela. | O split só funciona entre contas do mesmo grupo. A documentação técnica também chama o grupo de "Connect". | | **Fingerprinting** | Coleta de dados do navegador e do dispositivo usada pelo emissor para avaliar o risco no 3DS. | URL em `fingerprintingUrl`, renderizada em iframe oculto. O resultado vai em `fingerprintingResult`. | | **Frictionless** | Autenticação 3DS concluída sem pedir ação ao comprador, com base nos dados coletados. | No 3DS gerenciado, a cobrança segue direto e a resposta já traz o status final, sem `authentication_required`. | | **Idempotência** | Propriedade de uma operação que, repetida, produz o mesmo efeito que uma única execução. Evita cobranças duplicadas em retentativas. | O cabeçalho `Idempotency-Key` não existe hoje na API. Veja [Idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia#idempotência). | | **Item** | Cada produto ou serviço incluído na cobrança. | Campos obrigatórios: `title`, `type` (`physical` ou `digital`), `description`, `unit_price` e `quantity`. Item `physical` exige `shippingAddress` na cobrança. | | **JSON** | Formato de texto para troca de dados estruturados, com pares de nome e valor. | Corpo de todas as requisições e respostas, exceto uploads de arquivo (`multipart/form-data`). | | **JWT** | JSON Web Token: token assinado que carrega informações de identidade e validade. | O token de upload de documentos é um JWT, enviado como `Authorization: Bearer`. As demais rotas usam Basic com a chave. | | **KYC / KYB** | Know Your Customer / Know Your Business: verificação de identidade de pessoas e empresas antes de operar. | Análise cadastral das subcontas do Connect, com envio de documentos. Veja [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc). | | **Liquidação** | Etapa em que o valor de uma venda é acertado e passa a ser repassado a quem tem direito a ele. | No cartão, cada parcela é liquidada 30 dias corridos depois da criação da cobrança (D+30, D+60 e assim por diante). No Pix, no mesmo dia, logo após a confirmação do pagamento. No split, a parte de cada participante é repassada parcela a parcela, nesse mesmo momento, do saldo disponível do originador para o do recebedor. | | **Livemode** | Indicador de que um evento veio de produção. | Campo `livemode` no envelope do webhook: `false` em cobranças de teste. | | **MED** | Mecanismo Especial de Devolução: mecanismo do Pix, definido pelo Banco Central, que permite à instituição de quem pagou pedir a devolução de um Pix quando há fundada suspeita de fraude ou falha operacional. A instituição de quem recebeu analisa o pedido. Durante a análise, o valor fica bloqueado; se a contestação for aceita, ele é devolvido ao pagador. Não confundir com o bloqueio cautelar. | Não há status nem evento chamado MED. A cobrança continua `paid`, com `isBlocked: true`, e o evento `charge.blocked` é enviado aos endpoints e à `postbackUrl`. O alerta chega por e-mail à conta (no Connect, à conta master) e a defesa é enviada em resposta a esse e-mail, dentro do prazo indicado nele. Não há envio de defesa pela API. | | **Merchant** | Empresa cliente da Finvia que vende e recebe. Também chamada de lojista. | Campo `merchantId` nas respostas. | | **Metadata** | Informações livres do lojista guardadas junto a um objeto, como o número do pedido. | Campo `metadata` na cobrança e na assinatura. Não é filtro de busca em `GET /v1/charges`. | | **Modo Teste** | Ambiente de testes da Finvia, usado com a chave de teste. | A chave `sk_test_` é gerada no painel, em **Configurações > Chave de API**, aba **Teste**. As cobranças são simuladas; o cadastro de cartão e as assinaturas não. Os endpoints de webhook são os mesmos da produção: os eventos de teste trazem `livemode: false`. Veja [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes). | ## O a S | Termo | Definição | Na API da Finvia | | - | - | - | | **Originador** | No split, a conta que cria a cobrança. | É a conta cuja chave secreta foi usada em `POST /v1/charges`. Fica com o que sobra do líquido depois das partes do split. | | **Paginação** | Divisão de uma listagem em páginas para não devolver todos os registros de uma vez. | Parâmetros `page` (começa em 1) e `size` (padrão 10) em todas as listagens paginadas. `limit` é ignorado. `GET /v1/cards` e `GET /v1/wallets` devolvem lista sem paginação. | | **Parcelamento** | Divisão do valor de uma compra no cartão em parcelas mensais na fatura do comprador. | Campo `installments`, de 1 a 12 parcelas. | | **Payload** | O conteúdo transportado em uma requisição ou notificação, normalmente o corpo JSON. | | | **Payout** | Ver **Saque**. | | | **Pix** | Sistema brasileiro de pagamentos instantâneos. | `paymentMethod.type` igual a `pix`, com validade mínima de 900 segundos. Veja [Pix](/guias/cobrancas/pix). | | **Pix copia e cola** | Código de texto que representa uma cobrança Pix. O pagador cola esse código no app do banco quando não pode ler o QR Code. | Campo `copyPaste` em `paymentDetails`. | | **Plano** | Modelo de cobrança recorrente com preço, moeda e periodicidade. | Rotas em `/v1/subscription-plans`. Periodicidade: `weekly`, `biweekly`, `monthly` ou `custom`. | | **Portador** | Titular do cartão usado na compra. | | | **Postback** | Notificação enviada à URL informada em uma cobrança específica. | Campo `postbackUrl`. Recebe os mesmos eventos de cobrança dos endpoints, só daquela cobrança, e também o `charge.updated` legado, que não vai aos endpoints. | | **Pré-chargeback** | Alerta de contestação recebido antes de o chargeback ser formalizado, por programas das bandeiras. | Status `pre_chargeback`, avisado pelo evento `charge.pre_chargeback`. `chargebackAlertRefunded` (no webhook, `chargeback_alert_refunded`) diz se o valor já foi devolvido. | | **PSP** | Payment Service Provider: provedor que processa pagamentos em nome de lojistas. | Os campos `pspRefId` e `pspRefundRefId` trazem a referência da operação no provedor. | | **QR Code** | Código gráfico que o celular lê com a câmera. No Pix, carrega o BR Code da cobrança. | Imagem PNG de 256x256 em `qrCodeBase64`. Pode vir `null`: nesse caso, gere a imagem a partir do `copyPaste`. | | **Sandbox** | Ambiente de testes em que nenhuma transação é real. | Mesma URL da produção, com a chave `sk_test_`. Toda cobrança via `POST /v1/charges` é simulada, inclusive com cartão salvo. O cadastro de cartão e as assinaturas não têm sandbox, e não existe saque no sandbox ([detalhes](/primeiros-passos/credenciais-e-ambientes#o-que-é-simulado-no-modo-teste)). | | **Saque** | Transferência do saldo da conta para fora da Finvia. | Sempre por Pix, para a chave CNPJ da conta que saca, em `BRL`. Da própria conta em `POST /v1/payout-requests`; da subconta em `POST /v1/submerchants/{merchantId}/payout-requests` (mínimo R\$ 1,00). Status: `pending`, `approved` (aprovado e enviado para pagamento) e `rejected`. | | **Soft descriptor** | Nome curto que aparece na fatura do cartão do comprador. | Campo `softDescriptor` da subconta, com até 40 caracteres. | | **Split** | Divisão automática do valor de uma cobrança entre contas. | Campo `split` da cobrança, com `merchantId` e `percentage` (0,01 a 100). Aplicado por padrão sobre o valor líquido. Só entre contas do mesmo grupo Connect. Na consulta da cobrança, aparece em `splits`. Não vale para as cobranças recorrentes de assinatura. | | **Spread** | Spread aplicado à cobrança. | Campo `spread` da cobrança e dos webhooks. O campo `net` traz o valor líquido depois de aplicado o spread. | | **Status** | Situação atual de um objeto, como cobrança, assinatura ou saque. | Veja [Status de cobrança](/anexos/status-de-cobranca). | | **Subadquirente / subcredenciadora** | Empresa que processa pagamentos para lojistas usando a estrutura de um adquirente, concentrando o credenciamento de vários lojistas. | | | **Subconta** | No Connect, a conta de cada vendedor vinculada à conta master. Também chamada de SubMerchant. | Rotas em `/v1/submerchants`. Só opera com status `active`. Na criação, recebe uma cópia das taxas da conta master; depois disso, as taxas são independentes. | ## T a Z | Termo | Definição | Na API da Finvia | | - | - | - | | **Taxa de saque** | Valor cobrado por solicitação de saque. | Parte fixa mais percentual, configurada por conta. O valor transferido é `netAmount`. Valores de saque chegam como texto decimal (ex.: `"1.00000000"`). | | **Timeout** | Tempo esgotado sem resposta em uma requisição. O resultado da operação fica incerto. | Antes de repetir uma criação, confirme o estado. Veja [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia). | | **Token de cartão** | Identificador que substitui o número do cartão guardado no cofre. | O `id` devolvido por `POST /v1/cards`, usado como `cardTokenId`. | | **Token de upload** | Credencial temporária para enviar documentos sem expor a chave secreta. | Emitido por `POST /v1/submerchants/{merchantId}/document/upload-token`, expira em 300 segundos. | | **Trial** | Período de teste de um plano de assinatura, grátis ou pago. | Objeto `trial` do plano, com `durationDays` de 1 a 365 e `isFree`. | | **Valor bruto** | Valor total da venda, pago pelo cliente. | É o `amount` da cobrança. | | **Valor líquido** | O que sobra da venda depois das taxas da Finvia. | No split, o percentual de cada recebedor incide sobre o valor líquido. A cobrança traz o campo `net`, que o contrato descreve como o valor líquido depois de aplicado o spread. Veja [Cálculo de split](/guias/fast-connect/calculo-split). | | **Wallet (carteira)** | Saldo da conta por moeda. Também é o nome do objeto do Apple Pay na cobrança. | `GET /v1/wallets` traz `available`, `pending` e `reserved`. Na cobrança, `paymentMethod.wallet` carrega o token do Apple Pay. | | **Webhook** | Notificação HTTP POST que a Finvia envia ao seu servidor quando algo acontece. | Quatro famílias: cobrança, assinatura, saque e conta. Os endpoints são cadastrados no painel (**Configurações > Webhooks**) ou em `POST /v1/webhook-endpoints` e recebem cobrança, assinatura e saque (os de saque, só de subcontas). O aviso de status de subconta vai para a `postbackUrl` informada na criação da subconta. Veja o [Catálogo de eventos](/anexos/catalogo-de-eventos). | ## Veja também > [card] [Conceitos essenciais](/conceitos) > > Os objetos da API explicados com mais contexto. > [card] [Mapa da API](/mapa-da-api) > > Todas as rotas em uma página. > [card] [Status de cobrança](/anexos/status-de-cobranca) > > Cada status e o que fazer. > [card] [Catálogo de eventos](/anexos/catalogo-de-eventos) > > Todos os eventos de webhook. # 3DS gerenciado Source: https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado Crie a cobrança com threeDSMode managed, leve o comprador à authenticationUrl e acompanhe o resultado por webhook ou consulta. No 3DS gerenciado, a Finvia conduz a autenticação 3D Secure por você. O seu backend cria a cobrança de cartão com `threeDSMode: "managed"` e os dados do navegador do comprador. Quando o banco emissor pede uma verificação, a resposta traz uma `authenticationUrl`: você abre esse endereço para o comprador, e a página da Finvia faz a verificação do dispositivo, mostra o desafio do banco e conclui a cobrança. O resultado chega pelos webhooks e pela consulta da cobrança. > [!NOTE] > > **Para o negócio:** é a forma de 3DS com menos trabalho no checkout. A cobrança existe desde o início, com um `id` que você grava no pedido, e só é processada depois que o comprador conclui a autenticação. O comprador não volta sozinho para a loja ao final: o seu checkout precisa abrir a página de autenticação e acompanhar o resultado. ## Quando usar | Situação | Recomendação | | - | - | | Você quer delegar à Finvia as telas de verificação e de desafio | 3DS gerenciado | | Você quer o resultado do 3DS antes de criar a cobrança | [SDK](/guias/3d-secure/sdk) ou [3DS via API](/guias/3d-secure/via-api) | | Você precisa que o comprador volte automaticamente para uma página da loja ao final | Use o [SDK](/guias/3d-secure/sdk) ou o [3DS via API](/guias/3d-secure/via-api), que rodam dentro do seu checkout | | Apple Pay | Não se aplica | ## Como funciona O primeiro desenho mostra o que pode voltar na resposta da criação, conforme a política de 3DS da conta e a decisão do banco. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB CRI["POST /v1/charges
threeDSMode managed
+ browser"]:::lojista Q1{"A política de 3DS
da conta dispara?"}:::decisao Q2{"Veio browser e o
serviço de 3DS
funcionou?"}:::decisao Q3{"3DS obrigatório
na conta?"}:::decisao Q4{"O banco pede
verificação
ou desafio?"}:::decisao SEM(["Segue sem 3DS
status final na resposta"]):::neutro REC(["refused
3ds_required"]):::erro FIN(["Sem atrito
status final na resposta"]):::ok AUT(["authentication_required
com authenticationUrl"]):::alerta CRI --> Q1 Q1 -->|"não"| SEM Q1 -->|"sim"| Q2 Q2 -->|"não"| Q3 Q3 -->|"sim"| REC Q3 -->|"não"| SEM Q2 -->|"sim"| Q4 Q4 -->|"não"| FIN Q4 ==>|"sim"| AUT classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Só o caminho que termina em `authentication_required` exige que o comprador abra a página de autenticação. Nos outros, a resposta já traz o status final. O segundo desenho mostra esse caminho com autenticação, da criação da cobrança ao resultado. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant L as Sua loja (front-end e backend) end box rgb(234,243,255) Finvia participant F as Finvia API participant P as Página de autenticação end box rgb(244,240,255) Fora da Finvia participant E as Banco emissor end L->>F: POST /v1/charges · threeDSMode managed · browser F-->>L: 201 · authentication_required · authenticationUrl L->>P: Abre a authenticationUrl sem alterar (modal, iframe ou aba) alt Comprador conclui em até 15 minutos P->>E: Verificação do dispositivo do comprador P-->>C: Mostra o desafio do banco, quando pedido C->>P: Confirma a compra P->>F: POST /v1/three-ds/challenge-result P->>F: POST /v1/charges/{id}/resume-3ds Note over C,P: A página não leva o comprador de volta à loja F-)L: charge.paid, pending, refused ou failed L->>F: GET /v1/charges/{id} F-->>L: Status final da cobrança L-->>C: Fecha o modal e mostra o resultado else Abandona ou passa de 15 minutos Note over L,P: Fica em authentication_required, sem webhook e sem expirar sozinha. Depois de 15 minutos, crie outra cobrança end ``` As chamadas `challenge-result` e `resume-3ds` são feitas pela própria página de autenticação. A sua integração só cria a cobrança, abre a página e acompanha o resultado. **1. Crie a cobrança** O seu backend chama `POST /v1/charges` com a chave secreta, cartão, `paymentMethod.threeDSMode: "managed"` e `paymentMethod.browser`. Não envie `threeDS`. **2. A Finvia decide se o 3DS começa** O 3DS só é iniciado quando a política de 3DS da sua conta dispara: 3DS habilitado e obrigatório, ou valor da cobrança igual ou acima do mínimo configurado para a conta. **3. Leia a resposta** Se o banco aprova sem interação (autenticação sem atrito, ou frictionless), a resposta já traz o status final da cobrança. Se o banco pede verificação de dispositivo ou desafio, a resposta é `201` com `status` `authentication_required`, `reason` `Autenticação 3DS gerenciada necessária`, `paymentDetails` `null` e o campo `authenticationUrl`. **4. Leve o comprador à authenticationUrl** Abra o endereço recebido em um modal com iframe, em um iframe na página, em uma nova aba ou janela, ou redirecione na mesma aba. Use o valor exatamente como veio. **5. A página conduz a autenticação** A página de autenticação faz a verificação do dispositivo e o desafio do banco emissor. Ao final, ela mesma busca o resultado e retoma a cobrança (`POST /v1/three-ds/challenge-result` e `POST /v1/charges/{id}/resume-3ds`). Você não chama essas rotas. **6. Receba o resultado** O resultado chega pelos webhooks da cobrança e pelo postback na `postbackUrl`: `charge.paid`, `charge.pending`, `charge.refused` ou `charge.failed`. Você também pode consultar `GET /v1/charges/{id}`. **7. Trate o abandono** Se o comprador não concluir, a cobrança continua em `authentication_required`, sem expiração automática e sem webhook. Os dados do cartão ficam guardados por 15 minutos. Depois disso, a cobrança não pode mais ser concluída e é preciso criar outra. ## Regras de negócio | Regra | Detalhe | | - | - | | Campo de ativação | `paymentMethod.threeDSMode` com o valor `managed` | | Dados do navegador | `paymentMethod.browser` com `userAgent` e `ipAddress` (IP válido do comprador) obrigatórios. Os demais campos são opcionais | | Quando o 3DS começa | Só quando a política de 3DS da conta dispara (3DS obrigatório, ou valor igual ou acima do mínimo configurado) | | Quando aparece `authentication_required` | Só quando o banco pede verificação de dispositivo ou desafio. Sem atrito, a resposta já traz o status final | | Sem `browser` ou com falha do serviço de 3DS | A cobrança segue sem 3DS. Se o 3DS for obrigatório para a conta, ela é recusada com `reason` `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | | `authenticationUrl` | Endereço opaco. Não monte, não altere e não guarde para outra cobrança | | Quem retoma a cobrança | A própria página de autenticação | | Resultado | Webhooks `charge.paid`, `charge.pending`, `charge.refused`, `charge.failed`, ou `GET /v1/charges/{id}` | | Autenticação que não passa | Cobrança recusada com `reason` no formato `3ds_: Authentication did not succeed` | | Prazo para concluir | 15 minutos, que é o tempo em que os dados do cartão ficam guardados | | Cobrança abandonada | Fica em `authentication_required`, sem expiração automática e sem webhook | | Volta para a loja | Não há. A página não redireciona o comprador para o seu site | | Formas de pagamento | Cartão digitado e cartão salvo | > [!WARNING] > > Uma cobrança em `authentication_required` não foi paga. Não libere o pedido nesse status e não trate como paga uma cobrança abandonada. Libere só quando a cobrança chegar a `paid`, confirmada por webhook ou por `GET /v1/charges/{id}`. ## Passo a passo ### 1. Colete os dados do navegador | Campo de `browser` | Tipo | Obrigatório | Onde obter (sugestão) | | - | - | - | - | | `userAgent` | string | Sim | `navigator.userAgent` | | `ipAddress` | string | Sim | No seu servidor, a partir da requisição do comprador. Precisa ser um IP válido | | `acceptHeader` | string | Não | No seu servidor, cabeçalho `Accept` da requisição | | `language` | string | Não | `navigator.language` (ex.: `pt-BR`) | | `timezoneOffset` | integer | Não | `new Date().getTimezoneOffset()` (ex.: `-180`, conforme o contrato) | | `javascriptEnabled` | boolean | Não | `true` quando o script roda | | `javaEnabled` | boolean | Não | `navigator.javaEnabled()` | | `screenWidth` | integer | Não | `screen.width` | | `screenHeight` | integer | Não | `screen.height` | | `colorDepth` | integer | Não | `screen.colorDepth` | > [!TIP] > > **Para o desenvolvedor:** o contrato dá `-180` como exemplo de `timezoneOffset` para o horário de Brasília (UTC−3). O `getTimezoneOffset()` do JavaScript devolve `180` nesse fuso, com o sinal invertido. Converta antes de enviar. ```javascript theme={null} // No navegador: colete e envie ao seu backend junto com o pedido const browser = { userAgent: navigator.userAgent, language: navigator.language, timezoneOffset: -new Date().getTimezoneOffset(), javascriptEnabled: true, javaEnabled: navigator.javaEnabled(), screenWidth: screen.width, screenHeight: screen.height, colorDepth: screen.colorDepth, }; // ipAddress e acceptHeader são preenchidos pelo backend ``` ### 2. Crie a cobrança no backend ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 350, "currency": "BRL", "customer": { "name": "Ana Lima", "email": "ana@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "ANA LIMA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 2, "threeDSMode": "managed", "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } }, "items": [ { "title": "Mentoria online", "type": "digital", "description": "4 encontros", "unit_price": 350, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 350, "currency": "BRL", "customer": { "name": "Ana Lima", "email": "ana@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "ANA LIMA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 2, "threeDSMode": "managed", "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } }, "items": [ { "title": "Mentoria online", "type": "digital", "description": "4 encontros", "unit_price": 350, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" }' ``` ```javascript Node.js theme={null} const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', { method: 'POST', headers: { Authorization: 'Basic ' + Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'), 'Content-Type': 'application/json', }, body: JSON.stringify(cobranca), // mesmo corpo do exemplo em cURL }); const charge = await response.json(); if (charge.status === 'authentication_required') { // Devolva charge.authenticationUrl ao front-end e grave charge.id no pedido } else { // Sem atrito ou sem 3DS: o status já é o final (paid, refused, failed...) } ``` ```python Python theme={null} import os import requests payload = { "amount": 350, "currency": "BRL", "customer": { "name": "Ana Lima", "email": "ana@email.com", "document": { "type": "cpf", "id": "52998224725", }, "ipAddress": "177.128.144.97", }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "ANA LIMA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 2, "threeDSMode": "managed", "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": True, "javaEnabled": False, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24, }, }, "items": [ { "title": "Mentoria online", "type": "digital", "description": "4 encontros", "unit_price": 350, "quantity": 1, }, ], "postbackUrl": "https://meusite.com.br/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 350, 'currency' => 'BRL', 'customer' => [ 'name' => 'Ana Lima', 'email' => 'ana@email.com', 'document' => [ 'type' => 'cpf', 'id' => '52998224725', ], 'ipAddress' => '177.128.144.97', ], 'paymentMethod' => [ 'type' => 'credit_card', 'number' => '4111111111111111', 'holderName' => 'ANA LIMA', 'expirationMonth' => '10', 'expirationYear' => '2028', 'cvv' => '123', 'installments' => 2, 'threeDSMode' => 'managed', 'browser' => [ 'userAgent' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36', 'ipAddress' => '177.128.144.97', 'acceptHeader' => 'text/html,application/xhtml+xml', 'language' => 'pt-BR', 'timezoneOffset' => -180, 'javascriptEnabled' => true, 'javaEnabled' => false, 'screenWidth' => 1920, 'screenHeight' => 1080, 'colorDepth' => 24, ], ], 'items' => [ [ 'title' => 'Mentoria online', 'type' => 'digital', 'description' => '4 encontros', 'unit_price' => 350, 'quantity' => 1, ], ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 350, "currency": "BRL", "customer": { "name": "Ana Lima", "email": "ana@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "ANA LIMA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 2, "threeDSMode": "managed", "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } }, "items": [ { "title": "Mentoria online", "type": "digital", "description": "4 encontros", "unit_price": 350, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 350, "currency": "BRL", "customer": { "name": "Ana Lima", "email": "ana@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "ANA LIMA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 2, "threeDSMode": "managed", "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } }, "items": [ { "title": "Mentoria online", "type": "digital", "description": "4 encontros", "unit_price": 350, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 350, "currency": "BRL", "customer": { "name": "Ana Lima", "email": "ana@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "ANA LIMA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 2, "threeDSMode": "managed", "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } }, "items": [ { "title": "Mentoria online", "type": "digital", "description": "4 encontros", "unit_price": 350, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 350, "currency" => "BRL", "customer" => { "name" => "Ana Lima", "email" => "ana@email.com", "document" => { "type" => "cpf", "id" => "52998224725", }, "ipAddress" => "177.128.144.97", }, "paymentMethod" => { "type" => "credit_card", "number" => "4111111111111111", "holderName" => "ANA LIMA", "expirationMonth" => "10", "expirationYear" => "2028", "cvv" => "123", "installments" => 2, "threeDSMode" => "managed", "browser" => { "userAgent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress" => "177.128.144.97", "acceptHeader" => "text/html,application/xhtml+xml", "language" => "pt-BR", "timezoneOffset" => -180, "javascriptEnabled" => true, "javaEnabled" => false, "screenWidth" => 1920, "screenHeight" => 1080, "colorDepth" => 24, }, }, "items" => [ { "title" => "Mentoria online", "type" => "digital", "description" => "4 encontros", "unit_price" => 350, "quantity" => 1, }, ], "postbackUrl" => "https://meusite.com.br/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201` quando o banco pede verificação ou desafio: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "authentication_required", "paymentDetails": null, "reason": "Autenticação 3DS gerenciada necessária", "authenticationUrl": "https://" } ``` O valor de `authenticationUrl` no exemplo é ilustrativo. Use sempre o endereço que vier na resposta: o host pode mudar, e a URL carrega parâmetros da autenticação que não devem ser alterados. > [!NOTE] > > Quando o banco aprova sem interação, a mesma chamada devolve direto o status final (por exemplo, `paid`), sem `authenticationUrl`. Trate os dois casos no seu código. ### 3. Abra a página de autenticação Envie a `authenticationUrl` ao front-end e abra para o comprador. A página aceita ser exibida em iframe. ```html theme={null} ``` ```javascript theme={null} function abrirAutenticacao(authenticationUrl) { document.getElementById('iframe-3ds').src = authenticationUrl; document.getElementById('modal-3ds').hidden = false; aguardarResultado(); // veja o passo 4 } ``` Se preferir, abra em nova aba (`window.open(authenticationUrl, '_blank')`) ou redirecione a aba atual. No redirecionamento, o comprador não volta sozinho para a loja: ele fica na página de autenticação ao final. > [!WARNING] > > A página de autenticação não leva o comprador de volta ao seu site e não informa o resultado à sua página. Ao final, ela pode mostrar uma mensagem de confirmação ou ficar em branco. Não use o que a página exibe como resultado do pagamento. O resultado vale só pelo webhook ou pela consulta da cobrança. > [!NOTE] > > A página de autenticação ainda exibe o logotipo e o rodapé com o nome anterior da marca. Isso é esperado. ### 4. Acompanhe o resultado Ao concluir a autenticação, a página retoma a cobrança e a Finvia envia o evento correspondente aos seus endpoints de webhook e à `postbackUrl` da cobrança: | Evento | Quando | | - | - | | `charge.paid` | Cobrança aprovada | | `charge.pending` | O adquirente deixou a cobrança pendente | | `charge.refused` | Cobrança recusada. Se a autenticação não passou, `reason` vem no formato `3ds_: Authentication did not succeed` | | `charge.failed` | Falha no processamento | No front-end, enquanto o modal está aberto, consulte o seu backend para saber se o webhook já chegou. No backend, você pode confirmar com a consulta da cobrança: ```bash theme={null} curl "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI" \ -u "$FINVIA_API_KEY:" ``` Quando o status sair de `authentication_required`, feche o modal e mostre o resultado ao comprador. ### 5. Trate o abandono | Situação | O que acontece | O que fazer | | - | - | - | | O comprador fecha o modal sem concluir | A cobrança continua em `authentication_required` | Não libere o pedido. Ofereça uma nova tentativa com uma nova cobrança | | O comprador conclui depois de 15 minutos | A retomada falha com `Dados de autenticação expiraram. Crie uma nova cobrança.` e a cobrança não é processada | Crie uma nova cobrança | | O comprador nunca conclui | A cobrança fica em `authentication_required`, sem expiração automática e sem webhook | Defina no seu sistema um prazo para considerar o pedido abandonado | ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Resposta sem `authenticationUrl` e com status final | O banco aprovou sem atrito, ou a política de 3DS da conta não disparou | Siga com o status recebido | | Cobrança `refused` com `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | 3DS obrigatório na conta e a cobrança foi enviada sem `browser`, ou o serviço de 3DS falhou | Envie `browser` com `userAgent` e `ipAddress` válidos e tente com uma nova cobrança | | Cobrança `refused` com `3ds_: Authentication did not succeed` | O comprador não passou na autenticação do banco | Ofereça nova tentativa com outro cartão ou outra forma de pagamento | | Comprador fica parado na página de autenticação ao final | A página não redireciona para a loja | Abra a página em modal, iframe ou nova aba e acompanhe o resultado pelo seu backend | | Pedido liberado sem pagamento | O código tratou `authentication_required` como sucesso | Libere só com `paid` confirmado | | Cobrança presa em `authentication_required` | O comprador abandonou a autenticação | Considere o pedido abandonado depois do seu prazo e crie nova cobrança se o comprador voltar | ## Perguntas frequentes > [accordion] Preciso chamar resume-3ds ou challenge-result? > > Não. No 3DS gerenciado, a página aberta pela `authenticationUrl` faz essas chamadas. A sua integração só cria a cobrança, abre a página e acompanha o resultado. > [accordion] Toda cobrança com threeDSMode managed vai para authentication\_required? > > Não. Isso só acontece quando a política de 3DS da conta dispara e o banco pede verificação de dispositivo ou desafio. Na autenticação sem atrito, a resposta já traz o status final. Sem os dados do navegador ou com falha do serviço de 3DS, a cobrança segue sem 3DS, ou é recusada se o 3DS for obrigatório para a conta. > [accordion] Posso montar a authenticationUrl no meu código? > > Não. Use o valor recebido na resposta, sem alterar. O host e os parâmetros são definidos pela Finvia e podem mudar. > [accordion] O comprador volta para a minha loja ao final? > > Não. A página de autenticação não redireciona para o seu site. Por isso, a recomendação é abrir a página em modal, iframe ou nova aba e acompanhar o resultado por webhook ou consulta. > [accordion] Quanto tempo o comprador tem para concluir? > > Os dados do cartão ficam guardados por 15 minutos. Depois disso, a cobrança não pode mais ser concluída e é preciso criar outra. > [accordion] Posso usar o 3DS gerenciado com cartão salvo? > > Sim. A variante de cartão salvo aceita `threeDSMode` `managed`, com `browser` junto. ## Como testar O 3D Secure é homologado em um cenário específico da sua conta, conforme o [roteiro de homologação](/homologacao/roteiro). Inclua no teste: criação com `threeDSMode` `managed` que volte `authentication_required` com `authenticationUrl`, autenticação concluída na página com o webhook `charge.paid` recebido, e o tratamento de uma cobrança abandonada em `authentication_required`. ## Veja também > [card] [3D Secure: visão geral](/guias/3d-secure/visao-geral) > > Comparativo das três formas de integrar. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Campos `threeDSMode`, `browser` e `authenticationUrl`. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos que trazem o resultado. > [card] [Retomar cobrança](/referencia/3d-secure/retomar-cobranca) > > Rota usada pela página de autenticação. # SDK de segurança (3DS) Source: https://docs.fastpaybrasil.com/guias/3d-secure/sdk Faça a autenticação 3D Secure completa no front-end com o SDK de segurança e envie o resultado na criação da cobrança. O SDK de segurança faz a autenticação 3D Secure (3DS) inteira no navegador do comprador com uma única chamada, o método `process()`. Ele coleta os dados do navegador, abre o desafio do banco emissor em um modal quando necessário e devolve o resultado da autenticação. O seu backend envia esse resultado no campo `paymentMethod.threeDS` ao criar a cobrança. > [!NOTE] > > **Para o negócio:** o SDK é a forma de integrar o 3DS com menos código no checkout. O cliente vê a tela do banco só quando o emissor pede uma confirmação. Nos demais casos, a autenticação acontece sem interação. > [!NOTE] > > O pacote foi publicado com o nome anterior da marca: `@fastpaybr/security-sdk`. A classe exportada é `Client`, que também é o export padrão. Pelo CDN, ela fica em `FastPay.Client`. Também mantêm o nome anterior a classe de erro `FastPayError` e o prefixo `[FastPay]` nas mensagens de log de depuração. Esses nomes são esperados e só mudam com uma nova versão do SDK. ## Quando usar | Situação | Recomendação | | - | - | | Checkout web com cartão digitado e 3DS exigido pela conta | SDK | | Você quer a autenticação pronta antes de criar a cobrança | SDK | | Você precisa controlar cada tela e cada chamada | [3DS via API](/guias/3d-secure/via-api) | | Você prefere que a Finvia conduza o 3DS depois de criar a cobrança | [3DS gerenciado](/guias/3d-secure/gerenciado) | ## Como funciona O desenho abaixo mostra o que acontece entre o clique em pagar e a resposta da cobrança quando você usa o SDK. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant N as Seu checkout com o SDK participant L as Seu backend end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant E as Banco emissor end N->>N: Inicializa o SDK com a chave pública (pk_) C->>N: Informa o cartão e confirma a compra N->>F: process() · envia amount, currency, card e dados do navegador opt O emissor pede verificação do dispositivo N->>E: Fingerprinting em iframe oculto end alt O emissor pede confirmação N-->>C: Abre o modal com a tela do banco C->>E: Confirma a compra else Sem fricção Note over N,E: Segue sem interação do comprador end F-->>N: Resultado da autenticação · type e state alt state success N->>L: Envia o resultado como veio L->>F: POST /v1/charges · sk_ · cvv · installments · threeDS F-->>L: 201 · paid, refused ou failed L-->>C: Mostra o resultado do pedido else Outro state, ou modal fechado (type none, state failure) N-->>C: Com 3DS obrigatório, não crie a cobrança · ofereça nova tentativa end ``` O SDK roda no navegador com a chave pública. O CVV e as parcelas não passam pelo `process()`: eles vão só na criação da cobrança, feita pelo seu backend com a chave secreta. **1. Inicialize o SDK com a chave pública** Crie o `Client` com a chave pública (`pk_`) e chame `initialize()`. Confira `isThreeDSAvailable()`. **2. Chame process() com os dados da compra** Valor, moeda, cartão e cliente. O endereço é opcional. **3. O SDK coleta os dados do navegador** O SDK coleta sozinho os dados do navegador, inclusive o IP público do comprador, e, quando o emissor pede, faz o fingerprinting (verificação do dispositivo). **4. Desafio, quando necessário** Se o emissor pede confirmação, o SDK abre um modal com a tela do banco. Se não pede, o fluxo segue sem fricção. **5. Resultado** `process()` devolve o resultado com `state`. Se for `success`, envie o resultado ao seu backend. Se o comprador fechar o modal, o resultado é `{ type: 'none', state: 'failure' }`. **6. Seu backend cria a cobrança** `POST /v1/charges` com o resultado em `paymentMethod.threeDS`, usando a chave secreta. | `state` do resultado | O que acontece | | - | - | | `success` | Criar a cobrança com os dados 3DS | | `failure` | Falha na autenticação: transação recusada | | `unenrolled` | Cartão não inscrito | | `error` | Erro no processo | | `unsupported_brand` | Bandeira não suportada | | `disabled` | 3DS desabilitado | ## Regras de negócio | Regra | Detalhe | | - | - | | Chave usada no SDK | Chave pública (`pk_`). A chave secreta nunca vai para o navegador | | Cobrança | Criada pelo seu backend, com a chave secreta, depois da autenticação | | Estado que libera a cobrança | Só `success`, quando o 3DS é exigido pela configuração da conta. Sem 3DS obrigatório, os dados 3DS são repassados sem validação | | Dados de `process()` | `amount`, `currency`, `card` e `customer` obrigatórios; `address` opcional. `process()` não aceita `installments`: as parcelas vão só na cobrança | | O que o SDK envia à API | Só `amount`, `currency`, `card` e os dados do navegador, que ele coleta sozinho (inclusive o IP público). `customer` e `address` não são enviados | | Fechar o modal | `process()` não lança erro: devolve `{ type: 'none', state: 'failure' }` | ## Instalação > [tab] NPM > > ```bash theme={null} > npm install @fastpaybr/security-sdk > ``` > [tab] CDN > > ```html theme={null} > > ``` > > O script expõe o objeto global `FastPay`. A classe fica em `FastPay.Client` (ou `FastPay.default`). ## Inicialização ### Configuração básica ```javascript theme={null} import { Client } from '@fastpaybr/security-sdk' // ou: import FinviaClient from '@fastpaybr/security-sdk' (export padrão) const client = new Client({ credentials: { publicKey: 'pk_sua_chave_publica' }, debug: false }) await client.initialize() if (client.isThreeDSAvailable()) { console.log('3DS disponível e pronto para uso') } ``` ### Verificação de status ```javascript theme={null} // Verificar se o SDK foi inicializado if (client.isReady()) { console.log('SDK inicializado com sucesso') } // Verificar se o 3DS está disponível if (client.isThreeDSAvailable()) { console.log('3DS pronto para uso') } ``` ## Fluxo de autenticação ### Processo completo (recomendado) O método `process()` conduz todo o fluxo de autenticação: ```javascript theme={null} try { const result = await client.threeds.process( { // Dados da transação amount: 100.00, // Valor na moeda especificada currency: 'BRL', // Dados do cartão card: { number: '4111111111111111', holderName: 'Joao Silva', expirationMonth: '12', expirationYear: '2028' }, // Dados do cliente (obrigatório na tipagem do SDK) customer: { name: 'Joao Silva', email: 'joao@email.com', phone: '+5511987654321' }, // Endereço do cliente (opcional) address: { street: 'Av. Paulista', number: '1000', complement: 'Apto 51', zipCode: '01310100', neighborhood: 'Bela Vista', city: 'São Paulo', state: 'SP', country: 'BRA' } }, { // Opções (todas opcionais) fingerprintingTimeout: 60000, // Tempo limite do fingerprinting (padrão: 60s) challengeTimeout: 600000, // Tempo limite do desafio (padrão: 10min) modal: { width: '600px', // Largura do modal (padrão: 600px) height: '600px', // Altura do modal (padrão: 600px) showCloseButton: true // Mostrar botão de fechar } } ) // Resultado da autenticação console.log('Autenticação concluída:', result) if (result.state === 'success') { // Envie o resultado ao seu backend, que cria a cobrança const charge = await createCharge({ // ... outros dados da cobrança threeDS: result }) } } catch (error) { console.error('Erro na autenticação 3DS:', error) } ``` ### Estrutura do resultado ```typescript theme={null} interface ChallengeResultResponse { type: 'full' | 'partial' | 'none' state: 'success' | 'failure' | 'unenrolled' | 'error' | 'unsupported_brand' | 'disabled' // Dados da autenticação (quando state === 'success') cryptogram?: string // CAVV/AAV directoryServerTransactionId?: string // DS Transaction ID threeDsServerTransactionId?: string // 3DS Server Transaction ID acsTransactionId?: string // ACS Transaction ID eci?: string // Electronic Commerce Indicator version?: string // Versão do protocolo 3DS } ``` Os campos opcionais ficam ausentes quando não há valor; eles não vêm com `null`. Repasse o objeto ao backend como veio. > [!NOTE] > > Se o comprador fechar o modal do desafio, `process()` não lança erro. Ele devolve `{ type: 'none', state: 'failure' }`. Trate esse resultado como autenticação não concluída e ofereça nova tentativa. ### Estados de autenticação | Estado | Descrição | Ação recomendada | | - | - | - | | `success` | Autenticação bem-sucedida | Prosseguir com a cobrança | | `failure` | O cliente falhou na autenticação | Recusar a transação ou pedir outra forma de pagamento | | `unenrolled` | Cartão não inscrito no 3DS | Avaliar a sua política de risco | | `error` | Erro no processo de autenticação | Tentar de novo ou usar outra forma de pagamento | | `unsupported_brand` | A bandeira não suporta 3DS | Usar outra forma de pagamento | | `disabled` | 3DS desabilitado para este cartão | Avaliar a sua política de risco | ## Customização do modal ### Container personalizado Você pode indicar o seu próprio elemento para receber o iframe do desafio: ```javascript theme={null} // Container personalizado const customContainer = document.getElementById('my-3ds-container') const result = await client.threeds.process({ // ... dados da transação challengeContainer: customContainer }) ``` ```html theme={null}
``` ### Desabilitar o modal automático ```javascript theme={null} const result = await client.threeds.process( { // ... dados challengeContainer: document.getElementById('my-container') }, { modal: false // Desabilita o modal automático } ) ``` > [!WARNING] > > Com `modal: false`, informe `challengeContainer`. Sem o container, o SDK não tem onde mostrar o desafio e devolve o erro "container is required". ### Customizar a aparência do modal ```javascript theme={null} const result = await client.threeds.process( { /* ... dados */ }, { modal: { width: '800px', height: '700px', closeOnOverlayClick: false, // Impede fechar ao clicar fora (padrão: false) showCloseButton: false // Oculta o botão de fechar } } ) ``` ## Exemplos de implementação > [tab] React > > ```jsx theme={null} > import { useState } from 'react' > import { Client } from '@fastpaybr/security-sdk' > > function CheckoutForm() { > const [loading, setLoading] = useState(false) > const [result, setResult] = useState(null) > > const handleSubmit = async (formData) => { > setLoading(true) > > try { > const client = new Client({ > credentials: { publicKey: process.env.REACT_APP_FINVIA_PUBLIC_KEY } > }) > > await client.initialize() > > if (!client.isThreeDSAvailable()) { > throw new Error('3DS não disponível') > } > > const threeDSResult = await client.threeds.process({ > amount: formData.amount, > currency: 'BRL', > card: { > number: formData.cardNumber, > holderName: formData.cardHolder, > expirationMonth: formData.expMonth, > expirationYear: formData.expYear > }, > customer: { > name: formData.customerName, > email: formData.customerEmail, > phone: formData.customerPhone > }, > address: formData.address > }) > > if (threeDSResult.state === 'success') { > // Criar a cobrança com os dados 3DS (no seu backend) > const charge = await createCharge({ > ...formData, > threeDS: threeDSResult > }) > > setResult(charge) > } else { > throw new Error(`Autenticação falhou: ${threeDSResult.state}`) > } > } catch (error) { > console.error('Erro:', error) > alert(error.message) > } finally { > setLoading(false) > } > } > > return ( >
> {/* Campos do formulário */} > >
> ) > } > ``` > [tab] JavaScript puro > > ```html theme={null} > > > > Checkout com 3DS > > >
> > >
> > > > > > ``` > [tab] Vue.js > > ```vue theme={null} > > > > ``` > [!TIP] > > **Para o desenvolvedor:** nos exemplos, `createCharge` representa uma chamada ao **seu** backend. É o backend que chama `POST /v1/charges` com a chave secreta. ## Métodos disponíveis | Método | O que faz | Retorno | | - | - | - | | `client.initialize()` | Inicializa o SDK e carrega os provedores de 3DS disponíveis | `Promise` | | `client.isReady()` | Verifica se o SDK foi inicializado com sucesso | `boolean` | | `client.isThreeDSAvailable()` | Verifica se o 3DS está disponível e pronto para uso | `boolean` | | `client.threeds.process(request, options)` | Executa o fluxo completo de autenticação 3DS | `Promise` | ```javascript theme={null} await client.initialize() const ready = client.isReady() const available = client.isThreeDSAvailable() ``` ### Parâmetros de `process()` ```typescript theme={null} interface ThreeDSProcessRequest { amount: number // Valor na moeda especificada currency: string // Código da moeda (ex.: BRL) card: { number: string // Número do cartão holderName?: string // Nome do titular expirationMonth: string // Mês de validade (1-12) expirationYear: string // Ano de validade (4 dígitos) } customer: { name: string // Nome completo email: string // E-mail do cliente phone: string // Telefone com código do país } address?: { street: string // Logradouro number: string // Número complement?: string // Complemento (opcional) zipCode: string // CEP neighborhood: string // Bairro city: string // Cidade state: string // Estado country: string // País (código ISO 3166-1 alpha-3) } challengeContainer?: HTMLElement // Container personalizado para o desafio } interface ThreeDSProcessOptions { fingerprintingTimeout?: number // Tempo limite do fingerprinting em ms (padrão: 60000) challengeTimeout?: number // Tempo limite do desafio em ms (padrão: 600000) modal?: | { width?: string // Largura do modal (padrão: '600px') height?: string // Altura do modal (padrão: '600px') closeOnOverlayClick?: boolean // Fechar ao clicar fora (padrão: false) showCloseButton?: boolean // Mostrar o botão X (padrão: true) } | false // false para desabilitar o modal automático } ``` > [!NOTE] > > `customer` é obrigatório na tipagem e `address` é opcional. Nenhum dos dois vai para a API: o SDK envia só `amount`, `currency`, `card` e os dados do navegador, que ele coleta sozinho, inclusive o IP público do comprador. `process()` não recebe `installments`; as parcelas vão só na criação da cobrança. O tempo limite das requisições que o cliente do SDK faz à API aceita no máximo 30000 ms. ## Integração com a API de cobranças Depois de obter o resultado do 3DS, envie-o ao seu backend, que cria a cobrança com o resultado em `paymentMethod.threeDS`: ```javascript theme={null} // 1. No navegador: executar a autenticação 3DS const threeDSResult = await client.threeds.process({ amount: 100.00, currency: 'BRL', card: { /* ... */ }, customer: { /* ... */ } }) // 2. No backend: criar a cobrança incluindo os dados 3DS const charge = await fetch('https://api-global.fastpaybrasil.com/v1/charges', { method: 'POST', headers: { 'Authorization': `Basic ${credentials}`, // chave secreta, só no backend 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: 100.00, currency: 'BRL', customer: { name: 'Joao Silva', email: 'joao@email.com', document: { type: 'cpf', id: '52998224725' }, phone: '+5511987654321' }, paymentMethod: { type: 'credit_card', number: '4111111111111111', holderName: 'Joao Silva', expirationMonth: '12', expirationYear: '2028', cvv: '123', installments: 1, // Incluir os dados 3DS threeDS: threeDSResult }, items: [ { title: 'Produto XYZ', type: 'digital', description: 'Descrição', unit_price: 100.00, quantity: 1 } ] }) }) const result = await charge.json() console.log('Cobrança criada:', result) ``` > [!NOTE] > > Os campos do cartão na cobrança seguem o contrato de `POST /v1/charges`: `number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`, `installments` e `threeDS`. O `items[].unit_price` usa a mesma unidade do `amount`: valor decimal em reais. Para `amount: 100.00`, use `unit_price: 100.00`. Os nomes `cardNumber` e `cardholderName` não existem no contrato. ### Cenários de validação As validações abaixo só valem quando o 3DS é obrigatório para a sua conta. Nos outros casos, os dados 3DS são repassados sem validação. | Situação | `reason` da cobrança recusada | | - | - | | Cobrança sem `threeDS` | `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | | Falha de autenticação | `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card` | | Dados incompletos (`cryptogram` ou `eci` ausentes ou nulos) | `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` | | Tudo certo | A cobrança segue normalmente | ### Exemplos de erros ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "refused", "reason": "3ds_required: Não foi possível completar a autenticação 3DS obrigatória" } ``` ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "refused", "reason": "3ds_failed: The cardholder failed to authenticate. Please try again or use a different card" } ``` Os textos de `reason` aparecem aqui exatamente como a API devolve, sem ponto final. Trate a recusa pelo prefixo (`3ds_required`, `3ds_failed`, `3ds_incomplete`). ## Tratamento de erros ### Erros lançados pelo SDK Os erros lançados pelo SDK são instâncias de `FastPayError`, nome que vem da marca anterior. Com `debug: true`, as mensagens de log no console começam com `[FastPay]`. ```javascript theme={null} try { const result = await client.threeds.process({ /* ... */ }) } catch (error) { if (error.message.includes('not available')) { // O provedor de 3DS não está disponível console.error('3DS não disponível no momento') } else if (error.message.includes('timeout')) { // Tempo limite esgotado console.error('Tempo limite na autenticação') } else if (error.message.includes('container')) { // Container não informado quando necessário console.error('Container para o desafio não informado') } else { // Outros erros console.error('Erro desconhecido:', error) } } ``` ### Estados de erro no resultado ```javascript theme={null} const result = await client.threeds.process({ /* ... */ }) switch (result.state) { case 'success': // Autenticação bem-sucedida break case 'failure': // O cliente falhou na autenticação alert('A autenticação falhou. Tente de novo ou use outro cartão.') break case 'unenrolled': // Cartão não inscrito no 3DS // Decisão de negócio: aceitar ou recusar break case 'error': // Erro no processo alert('Erro na autenticação. Tente de novo.') break case 'unsupported_brand': // A bandeira não suporta 3DS alert('Este cartão não suporta 3D Secure.') break case 'disabled': // 3DS desabilitado alert('O 3D Secure está desabilitado para este cartão.') break } ``` ## Boas práticas > [accordion] 1. Sempre inicialize antes de usar > > ```javascript theme={null} > // Errado > const result = await client.threeds.process({ > /* ... */ > }) > > // Correto > await client.initialize() > if (client.isThreeDSAvailable()) { > const result = await client.threeds.process({ > /* ... */ > }) > } > ``` > [accordion] 2. Trate todos os estados > > ```javascript theme={null} > const result = await client.threeds.process({ > /* ... */ > }) > > // Sempre trate todos os estados possíveis > if (result.state === 'success') { > // Prosseguir com a cobrança > } else { > // Lidar com a falha de acordo com a sua política de negócio > handleAuthenticationFailure(result.state) > } > ``` > [accordion] 3. Use variáveis de ambiente para a chave > > Evite a chave fixa no código: > > ```javascript theme={null} > const client = new Client({ > credentials: { publicKey: 'pk_abc123' } > }) > ``` > > Prefira a variável de ambiente do build: > > ```javascript theme={null} > const client = new Client({ > credentials: { publicKey: process.env.FINVIA_PUBLIC_KEY } > }) > ``` > > A chave pública pode ir para o navegador; a variável de ambiente facilita trocar entre a chave de teste e a de produção. > [accordion] 4. Mostre o carregamento ao cliente > > ```javascript theme={null} > // Mostrar feedback visual ao cliente > setLoading(true) > try { > const result = await client.threeds.process({ > /* ... */ > }) > // Processar o resultado > } finally { > setLoading(false) > } > ``` > [accordion] 5. Ative o log de depuração só em desenvolvimento > > ```javascript theme={null} > const client = new Client({ > credentials: { publicKey: 'your_key' }, > debug: process.env.NODE_ENV === 'development' // Apenas em desenvolvimento > }) > ``` > [accordion] 6. Ajuste os tempos limite só se necessário > > Os valores padrão são 60 segundos para o fingerprinting e 10 minutos para o desafio: > > ```javascript theme={null} > const result = await client.threeds.process( > { > /* ... */ > }, > { > fingerprintingTimeout: 60000, // Padrão: 60s > challengeTimeout: 600000 // Padrão: 10min > } > ) > ``` > > * **Fingerprinting:** 60 segundos de espera pela verificação do dispositivo. > * **Desafio:** 10 minutos para o comprador concluir a confirmação no banco. Um valor menor encerra antes a espera no checkout. > * Se os tempos limite se repetem, investigue a causa antes de mudar o valor. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | O modal não aparece | O fluxo foi sem fricção (sem desafio), o modal foi bloqueado por bloqueador de pop-up ou o container personalizado está com `display:none` | Confira o resultado; se usar container, garanta que ele esteja visível | | Tempo limite no fingerprinting | Internet lenta do cliente, problema no provedor de 3DS ou bloqueio de scripts no navegador | Investigue a causa antes de mudar o padrão de 60 segundos | | `state` `failure` com `type` `none` | O comprador fechou o modal do desafio | Ofereça nova tentativa | | Erro "3DS provider not available" | SDK não inicializado, nenhum provedor de 3DS configurado para a conta ou erro na inicialização | Chame `initialize()` e confira `isThreeDSAvailable()`. Persistindo, fale com a Finvia | | Erro "container is required" | Modal desabilitado sem `challengeContainer` | Use o modal automático ou informe o container | | Cobrança `refused` com `3ds_required` | Cobrança criada sem `threeDS` | Envie o resultado do SDK em `paymentMethod.threeDS` | | Cobrança `refused` com `3ds_failed` | O titular não concluiu a autenticação | Peça para tentar de novo ou usar outro cartão | | Dados do cartão inválidos | Número ou validade com erro de digitação | Valide os dados no formulário antes de chamar o SDK | ### Solução de problemas > [accordion] Modal não aparece > > ```javascript theme={null} > // Verificar se houve desafio > console.log('Resultado:', result) > > // Garantir que o container está visível > const container = document.getElementById('container') > container.style.display = 'block' > ``` > [accordion] Tempo limite no fingerprinting > > O padrão é 60 segundos. Tempos limite frequentes indicam problemas de rede, de bloqueio de scripts ou no provedor de 3DS, que precisam ser investigados. Ative `debug: true` em desenvolvimento e procure no console as mensagens com o prefixo `[FastPay]`. > [accordion] Erro 3DS provider not available > > ```javascript theme={null} > await client.initialize() > > if (!client.isThreeDSAvailable()) { > console.error('3DS não disponível. Verifique a configuração da conta.') > // Implementar alternativa ou avisar o cliente > } > ``` > [accordion] Erro container is required > > Opção 1: use o modal automático (padrão). > > ```javascript theme={null} > const result = await client.threeds.process({ > /* ... */ > }) > ``` > > Opção 2: informe o container se o modal estiver desabilitado. > > ```javascript theme={null} > const result = await client.threeds.process( > { > /* ... */ > challengeContainer: document.getElementById('my-container') > }, > { modal: false } > ) > ``` > [accordion] Dados do cartão inválidos > > ```javascript theme={null} > // Validar os dados antes de chamar o SDK > function validateCard(cardNumber, month, year) { > if (!isValidCardNumber(cardNumber)) { > alert('Número do cartão inválido') > return false > } > > if (!isValidExpiration(month, year)) { > alert('Data de validade inválida') > return false > } > > return true > } > ``` ## Perguntas frequentes > [accordion] Qual chave uso no SDK? > > A chave pública (`pk_`). Ela foi feita para o navegador. A chave secreta fica só no backend, que cria a cobrança. > [accordion] Preciso enviar o CVV ao SDK? > > Não. O `process()` recebe número, nome, mês e ano do cartão. O CVV vai só na criação da cobrança, feita pelo seu backend. > [accordion] O SDK cria a cobrança? > > Não. O SDK só autentica. A cobrança é criada pelo seu backend com `POST /v1/charges`, levando o resultado em `paymentMethod.threeDS`. > [accordion] O que acontece se o comprador fechar o modal? > > `process()` não lança erro. Ele devolve `{ type: 'none', state: 'failure' }`. Não crie a cobrança com esse resultado; ofereça nova tentativa. > [accordion] Por que o pacote e a classe de erro usam o nome anterior da marca? > > O SDK foi publicado com o nome anterior da marca. O pacote `@fastpaybr/security-sdk`, o global `FastPay` do CDN, a classe de erro `FastPayError` e o prefixo `[FastPay]` nos logs continuam assim até uma nova versão do SDK. > [accordion] O que fazer quando o estado é unenrolled ou disabled? > > A decisão é da sua política de risco. Se a sua conta exige 3DS, só `success` permite seguir com a cobrança. ## Como testar O 3D Secure é homologado em um cenário específico da sua conta, conforme o [roteiro de homologação](/homologacao/roteiro). No teste, inclua: autenticação com `state` `success` seguida de cobrança `paid`, cobrança sem `threeDS` (recusa com `3ds_required`) e o tratamento de cada `state` diferente de `success` no seu checkout. ## Veja também > [card] [3D Secure: visão geral](/guias/3d-secure/visao-geral) > > Comparativo das três formas de integrar. > [card] [3DS via API](/guias/3d-secure/via-api) > > As mesmas etapas, chamadas uma a uma. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Campo `paymentMethod.threeDS`. > [card] [Cartão de crédito](/guias/cobrancas/cartao-de-credito) > > Cobrança com cartão digitado. # 3DS via API Source: https://docs.fastpaybrasil.com/guias/3d-secure/via-api Conduza a autenticação 3D Secure etapa por etapa pelas rotas de 3DS e envie o resultado na criação da cobrança. No 3DS via API, a sua aplicação conduz cada etapa da autenticação 3D Secure. Ela inicia a autenticação, exibe o iframe de coleta de dados do navegador e envia o resultado. Depois, exibe o desafio do banco quando ele é pedido e, no fim, busca o resultado com o criptograma. Com esse resultado, o seu backend cria a cobrança informando o objeto `threeDS`. É o mesmo fluxo que o SDK faz por dentro, com controle total sobre cada tela. > [!NOTE] > > **Para o negócio:** esta forma dá ao seu time controle completo sobre a experiência do checkout durante a autenticação, ao custo de mais desenvolvimento. Se esse controle não for necessário, o [SDK](/guias/3d-secure/sdk) entrega o mesmo resultado com menos código. ## Quando usar | Situação | Recomendação | | - | - | | Você precisa controlar cada tela e cada etapa do 3DS | 3DS via API | | Seu checkout não pode carregar bibliotecas externas | 3DS via API | | Você quer menos código no front-end | [SDK](/guias/3d-secure/sdk) | | Você quer que a Finvia conduza a autenticação depois de criar a cobrança | [3DS gerenciado](/guias/3d-secure/gerenciado) | ## As rotas Todas as rotas de 3DS usam a **chave pública** (`pk_`) no cabeçalho Basic, porque são chamadas a partir do navegador. | Rota | Para que serve | | - | - | | `POST /v1/three-ds/authenticate` | Inicia a autenticação. Pode devolver `fingerprintingUrl` ou `challengeUrl` | | `POST /v1/three-ds/submit` | Envia a autenticação depois do fingerprinting. Pode devolver `challengeUrl` | | `POST /v1/three-ds/cancel` | Cancela uma autenticação em `requires_submission` ou `requires_challenge` | | `POST /v1/three-ds/challenge-result` | Busca o resultado final, com o criptograma e os IDs da transação | ## Como funciona O desenho abaixo mostra a sequência completa de chamadas, com os dois passos que só acontecem quando o emissor pede: a verificação do dispositivo e o desafio. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant N as Seu checkout (navegador, pk_) participant L as Seu backend (sk_) end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant P as Provedor de 3DS e emissor end N->>F: POST /v1/three-ds/authenticate · amount, currency, card, browser F-->>N: authenticationId · status · fingerprintingUrl ou challengeUrl opt status requires_submission opt Veio fingerprintingUrl N->>P: Carrega a fingerprintingUrl em iframe oculto P-)N: postMessage · fingerprinting-complete · fingerprintingResult end N->>F: POST /v1/three-ds/submit · authenticationId (+ fingerprintingResult) F-->>N: requires_challenge, succeeded, failed, error ou processing end opt requires_challenge (do authenticate ou do submit) N->>P: Mostra a challengeUrl em iframe visível, em até 30 s C->>P: Confirma a compra na tela do banco P-)N: postMessage · challenge-complete end N->>F: POST /v1/three-ds/challenge-result · authenticationId F-->>N: state · cryptogram · eci · version · IDs da transação N->>L: Envia o resultado como veio L->>F: POST /v1/charges · paymentMethod.threeDS F-->>L: 201 · paid, refused ou failed ``` As mensagens `postMessage` chegam com o `type` completo (`3ds-authentication-fingerprinting-complete` e `3ds-authentication-challenge-complete`). O `status` da mensagem de fim do desafio é só informativo: o resultado que vale é o de `challenge-result`. **1. Inicie a autenticação** O navegador chama `POST /v1/three-ds/authenticate` com valor, moeda, dados do cartão e dados do navegador. A resposta traz o `authenticationId` e o `status`. **2. Verificação do dispositivo em iframe oculto** Se o `status` for `requires_submission` com `fingerprintingUrl`, carregue essa URL em um iframe oculto e aguarde a mensagem `3ds-authentication-fingerprinting-complete`, com o `fingerprintingResult`. Se ela não chegar em cerca de 60 segundos, siga sem ele. **3. Envie a autenticação** Chame `POST /v1/three-ds/submit` com o `authenticationId` e, se houver, o `fingerprintingResult`. Se o `status` era `requires_submission` sem `fingerprintingUrl`, chame o `submit` direto. A resposta traz o novo `status`. **4. Desafio em iframe visível** Se o `status` for `requires_challenge` (vindo do `authenticate` ou do `submit`), carregue a `challengeUrl` em um iframe visível em até 30 segundos. O cliente confirma a compra na tela do banco, e a página avisa o fim com a mensagem `3ds-authentication-challenge-complete`. **5. Busque o resultado** Depois da mensagem de fim do desafio, ou quando `authenticate` ou `submit` já devolveram status final, chame `POST /v1/three-ds/challenge-result` com o `authenticationId`. A resposta traz `state`, `cryptogram`, `eci`, `version` e os IDs da transação. **6. Crie a cobrança com threeDS** O seu backend chama `POST /v1/charges` com o resultado em `paymentMethod.threeDS`, usando a chave secreta. ### Status da autenticação | `status` | Significado | Próximo passo | | - | - | - | | `requires_submission` | Aguardando o envio (depois do fingerprinting, se houver) | `submit` | | `requires_challenge` | O emissor pede desafio | Mostrar `challengeUrl` em iframe visível | | `processing` | Em processamento | Aguardar | | `succeeded` | Autenticação concluída com sucesso | `challenge-result` | | `failed` | Autenticação falhou | `challenge-result` para obter o `state` e decidir | | `error` | Erro na autenticação | `challenge-result` para obter o `state`; tentar de novo ou usar outra forma de pagamento | | `canceled` | Autenticação cancelada | Recomeçar, se o cliente quiser | Em estados finais, a resposta pode trazer `outcome`, com um destes valores: `authenticated`, `informational`, `attempt_acknowledged`, `rejected`, `denied`, `abandoned`, `not_supported`, `processing_error`, `internal_error` ou `canceled`. > [!NOTE] > > Os `status` acima são da **autenticação**, não da cobrança. A cobrança só é criada no fim, com o `state` devolvido por `challenge-result`. O desenho abaixo mostra qual rota chamar a partir de cada `status` da autenticação. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB AUTH["POST
/v1/three-ds/authenticate"]:::lojista Q1{"Veio
fingerprintingUrl?"}:::decisao FP["Iframe oculto
espera a mensagem até ~60 s"]:::lojista SUB["POST
/v1/three-ds/submit"]:::lojista CH["Desafio: challengeUrl em
iframe visível, aberto em
até 30 s, espera ~10 min"]:::alerta CANC(["POST /v1/three-ds/cancel
status canceled"]):::erro RES["POST /v1/three-ds/
challenge-result
devolve o state"]:::lojista Q2{"state é
success?"}:::decisao COB(["Backend cria a cobrança
com threeDS"]):::ok OUT(["Com 3DS obrigatório:
nova tentativa
ou outro meio"]):::erro AUTH -->|"requires_submission"| Q1 Q1 -->|"sim"| FP Q1 -->|"não"| SUB FP -->|"com ou sem
fingerprintingResult"| SUB AUTH -->|"requires_challenge"| CH SUB -->|"requires_challenge
depois do envio"| CH AUTH -->|"status final"| RES SUB -->|"succeeded, failed
ou error"| RES CH ==>|"mensagem de fim
do desafio"| RES CH -.->|"cliente desiste
ou o tempo acaba"| CANC RES --> Q2 Q2 ==>|"sim"| COB Q2 -->|"não"| OUT classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 ``` Se `authenticate` ou `submit` devolverem `processing`, aguarde antes de seguir. O cancelamento só vale para autenticações em `requires_submission` ou `requires_challenge`. ## Regras de negócio | Regra | Detalhe | | - | - | | Chave nas rotas de 3DS | Pública (`pk_`) | | Chave na cobrança | Secreta (`sk_`), no backend | | Obrigatórios em `authenticate` | `amount`, `currency`, `card` (com `number`, `expirationMonth`, `expirationYear`) e `browser` (com `userAgent` e `ipAddress`) | | Obrigatório em `submit`, `cancel` e `challenge-result` | `authenticationId` | | `fingerprintingResult` | Opcional em `submit`. Omita se não houve fingerprinting ou se a mensagem não chegou em cerca de 60 segundos | | Ordem das chamadas | `authenticate`, iframe de verificação, `submit`, desafio, `challenge-result` e, no backend, `POST /v1/charges` | | Tempo do desafio | Exiba a `challengeUrl` em até 30 segundos e espere no máximo cerca de 10 minutos. Para desistir, use `cancel` | | `authenticationId` | Texto opaco gerado pelo provedor de 3DS. Repasse sem validar prefixo nem tamanho | | Cancelamento | Só para autenticações em `requires_submission` ou `requires_challenge` | | Cobrança | Só `state` `success` permite seguir quando o 3DS é exigido pela configuração da conta | | Erro `404` | `No 3DS provider configured for this gateway`: a conta não tem provedor de 3DS configurado | | Erro `401` | `Unauthorized`: chave pública inválida | ## Passo a passo Os exemplos usam `fetch` no navegador com a chave pública. Defina uma função auxiliar: ```javascript theme={null} const FINVIA_PUBLIC_KEY = 'pk_sua_chave_publica'; const API = 'https://api-global.fastpaybrasil.com'; async function chamar3ds(rota, corpo) { const response = await fetch(`${API}${rota}`, { method: 'POST', headers: { Authorization: 'Basic ' + btoa(`${FINVIA_PUBLIC_KEY}:`), 'Content-Type': 'application/json', }, body: JSON.stringify(corpo), }); if (!response.ok) throw new Error(`3DS ${rota} respondeu ${response.status}`); return response.json(); } ``` ### 1. Inicie a autenticação ```http REST (JSON) theme={null} POST /v1/three-ds/authenticate HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 100, "currency": "BRL", "card": { "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028" }, "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/authenticate" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "BRL", "card": { "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028" }, "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } }' ``` ```javascript Navegador theme={null} const inicio = await chamar3ds('/v1/three-ds/authenticate', { amount: 100, currency: 'BRL', card: { number: cartao.numero, holderName: cartao.nome, expirationMonth: cartao.mes, expirationYear: cartao.ano, }, browser: { userAgent: navigator.userAgent, ipAddress: ipDoCliente, // obtido pelo seu backend language: navigator.language, timezoneOffset: -new Date().getTimezoneOffset(), javascriptEnabled: true, screenWidth: screen.width, screenHeight: screen.height, colorDepth: screen.colorDepth, }, }); ``` Resposta `200`: ```json theme={null} { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "requires_submission", "fingerprintingUrl": "https://provedor-3ds.exemplo.com/fingerprint/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "challengeUrl": null, "outcome": null } ``` > [!TIP] > > **Para o desenvolvedor:** o `cvv` não faz parte da autenticação. Ele vai só na criação da cobrança, feita pelo backend. ### 2. Faça a verificação do dispositivo em um iframe oculto Se o `status` for `requires_submission` e vier `fingerprintingUrl`, carregue a URL em um iframe oculto. Quando a coleta termina, a página do provedor de 3DS envia à sua janela, por `postMessage`, esta mensagem: ```json theme={null} { "type": "3ds-authentication-fingerprinting-complete", "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==" } ``` O `fingerprintingResult` é um texto em Base64 que você repassa ao `submit` sem alterar. ```javascript theme={null} function esperarMensagem(iframe, tipo, tempoLimiteMs) { return new Promise((resolve) => { function aoReceber(event) { // Aceite só mensagens do iframe que você criou e do tipo esperado if (event.source !== iframe.contentWindow) return; if (event.data?.type !== tipo) return; encerrar(event.data); } function encerrar(dados) { window.removeEventListener('message', aoReceber); clearTimeout(timer); resolve(dados); } window.addEventListener('message', aoReceber); const timer = setTimeout(() => encerrar(null), tempoLimiteMs); }); } let fingerprintingResult; if (inicio.status === 'requires_submission' && inicio.fingerprintingUrl) { const iframe = document.createElement('iframe'); iframe.style.display = 'none'; const mensagem = esperarMensagem(iframe, '3ds-authentication-fingerprinting-complete', 60000); iframe.src = inicio.fingerprintingUrl; document.body.appendChild(iframe); const dados = await mensagem; iframe.remove(); fingerprintingResult = dados?.fingerprintingResult; // undefined se o tempo acabou } ``` > [!WARNING] > > Quem envia a mensagem é a página do provedor de 3DS carregada no iframe, e o host dela pode mudar. Valide `event.source === iframe.contentWindow` e `event.data.type`. Não fixe um domínio de provedor em `event.origin`. > [!TIP] > > **Para o desenvolvedor:** se a mensagem não chegar em cerca de 60 segundos (o padrão do SDK), chame o `submit` sem `fingerprintingResult`. O campo é opcional. Se o `status` for `requires_submission` sem `fingerprintingUrl`, chame o `submit` direto. ### 3. Envie a autenticação ```http REST (JSON) theme={null} POST /v1/three-ds/submit HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/submit" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==" }' ``` ```javascript Navegador theme={null} // O submit só é necessário quando o status inicial é requires_submission const envio = inicio.status === 'requires_submission' ? await chamar3ds('/v1/three-ds/submit', { authenticationId: inicio.authenticationId, ...(fingerprintingResult ? { fingerprintingResult } : {}), }) : inicio; ``` Resposta `200`: ```json theme={null} { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "requires_challenge", "challengeUrl": "https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "outcome": null } ``` O `submit` devolve um destes status: `requires_challenge`, `succeeded`, `failed`, `error` ou `processing`. ### 4. Mostre o desafio em um iframe visível Quando o `status` é `requires_challenge`, a `challengeUrl` (que pode vir tanto do `authenticate` quanto do `submit`) precisa ser exibida ao cliente em um iframe visível, em até 30 segundos. * Não use o atributo `sandbox` no iframe. Alguns emissores falham com ele. * Tamanhos recomendados: 250×400, 390×400, 500×600, 600×400 ou tela cheia. * Espere no máximo cerca de 10 minutos. Depois disso, cancele a autenticação. ```html theme={null} ``` Quando o cliente termina, a página do desafio envia esta mensagem por `postMessage`: ```json theme={null} { "type": "3ds-authentication-challenge-complete", "status": "succeeded" } ``` O `status` da mensagem pode ser `succeeded`, `failed`, `error` ou `canceled`. Ele é só informativo: o resultado que vale é o devolvido por `challenge-result` no passo 5. ```javascript theme={null} const challengeUrl = envio.challengeUrl || inicio.challengeUrl; if (envio.status === 'requires_challenge' && challengeUrl) { const iframe = document.getElementById('iframe-3ds'); const fim = esperarMensagem(iframe, '3ds-authentication-challenge-complete', 10 * 60 * 1000); iframe.src = challengeUrl; document.getElementById('desafio-3ds').hidden = false; const dados = await fim; document.getElementById('desafio-3ds').hidden = true; if (!dados) { // Tempo esgotado: cancele a autenticação (veja abaixo) } } ``` > [!NOTE] > > Neste fluxo não há redirecionamento: o fim do desafio é avisado só pela mensagem `postMessage`. Os campos `challenge.returnUrl` e `deviceData` do objeto `threeDS` não se aplicam ao 3DS da Finvia (SDK, via API ou gerenciado) e são ignorados. Não é preciso enviá-los. Se o cliente desistir, cancele a autenticação: ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/cancel" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X" }' ``` Resposta `200`: ```json theme={null} { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "canceled" } ``` ### 5. Busque o resultado Depois da mensagem de fim do desafio, ou quando `authenticate` ou `submit` já devolveram status final (`succeeded`, `failed`, `error` ou `canceled`), busque o resultado: ```http REST (JSON) theme={null} POST /v1/three-ds/challenge-result HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/challenge-result" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X" }' ``` ```javascript Navegador theme={null} const resultado = await chamar3ds('/v1/three-ds/challenge-result', { authenticationId: inicio.authenticationId, }); if (resultado.state !== 'success') { // Mostre a mensagem adequada e ofereça outra forma de pagamento } ``` Resposta `200`: ```json theme={null} { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746", "eci": "05", "version": "2.2.0" } ``` | Campo | O que é | | - | - | | `type` | Tipo de autenticação (ex.: `full`) | | `state` | `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled` | | `cryptogram` | CAVV, o valor de autenticação | | `eci` | Electronic Commerce Indicator (`05` autenticado, `06` tentativa, `07` não autenticado) | | `version` | Versão do protocolo 3DS | | `directoryServerTransactionId`, `threeDsServerTransactionId`, `acsTransactionId` | IDs da transação na bandeira, no 3DS Server e no emissor | > [!WARNING] > > Não chame `challenge-result` antes do fim do desafio. Nesse caso, a rota responde `500` com a mensagem `Authentication challenge not yet completed...` ou devolve `state` `error`. ### 6. Crie a cobrança com o objeto threeDS O navegador envia o resultado ao seu backend, que cria a cobrança com a chave secreta. O objeto devolvido por `challenge-result` vai em `paymentMethod.threeDS`. ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "installments": 1, "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746" } }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "installments": 1, "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746" } }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" }' ``` ```python Python theme={null} import os import requests payload = { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725", }, "ipAddress": "177.128.144.97", }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "installments": 1, "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746", }, }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1, }, ], "postbackUrl": "https://meusite.com.br/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 100, 'currency' => 'BRL', 'customer' => [ 'name' => 'Joao Silva', 'email' => 'joao@email.com', 'document' => [ 'type' => 'cpf', 'id' => '52998224725', ], 'ipAddress' => '177.128.144.97', ], 'paymentMethod' => [ 'type' => 'credit_card', 'number' => '4111111111111111', 'holderName' => 'JOAO SILVA', 'expirationMonth' => '12', 'expirationYear' => '2028', 'cvv' => '123', 'installments' => 1, 'threeDS' => [ 'type' => 'full', 'state' => 'success', 'cryptogram' => 'Vt5xwasruB0Q6qRoG9mpzdRPqQs=', 'eci' => '05', 'version' => '2.2.0', 'directoryServerTransactionId' => '607bb317-8d24-45a7-a3c0-7ae1fdca56d0', 'threeDsServerTransactionId' => '59588a8b-955e-4aa8-bae1-338bbfdba8fa', 'acsTransactionId' => '6bf18a7a-3a7b-488f-bce1-3da96c73e746', ], ], 'items' => [ [ 'title' => 'Produto XYZ', 'type' => 'digital', 'description' => 'Descrição do produto', 'unit_price' => 100, 'quantity' => 1, ], ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "installments": 1, "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746" } }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "installments": 1, "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746" } }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "installments": 1, "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746" } }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://meusite.com.br/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 100, "currency" => "BRL", "customer" => { "name" => "Joao Silva", "email" => "joao@email.com", "document" => { "type" => "cpf", "id" => "52998224725", }, "ipAddress" => "177.128.144.97", }, "paymentMethod" => { "type" => "credit_card", "number" => "4111111111111111", "holderName" => "JOAO SILVA", "expirationMonth" => "12", "expirationYear" => "2028", "cvv" => "123", "installments" => 1, "threeDS" => { "type" => "full", "state" => "success", "cryptogram" => "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci" => "05", "version" => "2.2.0", "directoryServerTransactionId" => "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId" => "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId" => "6bf18a7a-3a7b-488f-bce1-3da96c73e746", }, }, "items" => [ { "title" => "Produto XYZ", "type" => "digital", "description" => "Descrição do produto", "unit_price" => 100, "quantity" => 1, }, ], "postbackUrl" => "https://meusite.com.br/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` > [!NOTE] > > A resposta de `challenge-result` nunca traz campos com `null`: quando não há valor (por exemplo, `cryptogram` numa autenticação sem sucesso), o campo fica ausente. Repasse o objeto como veio. O objeto `threeDS` da cobrança exige `type` e `state`; com `state` `success`, `cryptogram` e `eci` são, na prática, obrigatórios. Nos campos opcionais, omita o campo quando não tiver valor e não envie `null`. Não envie `mode`, que é de uso interno. A resposta da cobrança é a de sempre: `id`, `status` (`paid`, `refused` ou `failed`), `paymentDetails` e `reason`. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `No 3DS provider configured for this gateway` | Nenhum provedor de 3DS configurado para a conta | Fale com o time Finvia para habilitar o 3DS | | `401` `Unauthorized` | Chave pública inválida ou de outro ambiente | Use a `pk_` (ou `pk_test_`) da conta | | Verificação do dispositivo não termina | Mensagem não recebida, filtro pelo `type` errado ou listener registrado depois do iframe | Filtre por `3ds-authentication-fingerprinting-complete`, registre o listener antes e, depois de cerca de 60 segundos, siga sem `fingerprintingResult` | | Desafio não carrega ou falha no emissor | Iframe com o atributo `sandbox` | Remova o atributo `sandbox` | | `500` em `challenge-result` | Chamada antes do fim do desafio | Espere a mensagem `3ds-authentication-challenge-complete` | | Tentativa de cancelar uma autenticação já concluída | O cancelamento só vale para `requires_submission` e `requires_challenge` | Consulte o resultado com `challenge-result` | | Cobrança `refused` com `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | Cobrança criada sem `threeDS` numa conta com 3DS obrigatório | Envie o resultado em `paymentMethod.threeDS` | | Cobrança `refused` com `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` | `cryptogram` ou `eci` ausentes ou nulos | Envie o objeto completo devolvido por `challenge-result`, sem `null` | ## Perguntas frequentes > [accordion] Sempre vai ter fingerprinting e desafio? > > Não. A resposta de `authenticate` pode trazer `fingerprintingUrl`, `challengeUrl` ou nenhum dos dois, conforme o emissor. Trate cada caso pelo `status`. > [accordion] Qual a diferença entre status, outcome e state? > > `status` mostra em que etapa a autenticação está. `outcome` aparece nos estados finais e detalha como ela terminou. `state` é o resultado devolvido por `challenge-result`, usado no objeto `threeDS` da cobrança. > [accordion] Posso chamar as rotas de 3DS pelo backend? > > As rotas usam a chave pública e foram desenhadas para o navegador, que exibe os iframes. A criação da cobrança, essa sim, é sempre feita pelo backend, com a chave secreta. > [accordion] Para que serve challenge.returnUrl? > > No 3DS da Finvia, esse campo não tem uso. O fim do desafio é avisado pela mensagem `postMessage`, sem redirecionamento. Os campos `challenge.returnUrl` e `deviceData` são ignorados; não é preciso enviá-los. > [accordion] Uso o mesmo resultado em mais de uma cobrança? > > A documentação não prevê isso. Faça uma autenticação para cada cobrança. ## Como testar O 3D Secure é homologado em um cenário específico da sua conta, conforme o [roteiro de homologação](/homologacao/roteiro). Inclua no teste os caminhos com e sem fingerprinting, com e sem desafio, o cancelamento e a cobrança com `state` `success`. ## Veja também > [card] [Iniciar autenticação](/referencia/3d-secure/iniciar) > > Referência de `POST /v1/three-ds/authenticate`. > [card] [Resultado do desafio](/referencia/3d-secure/resultado-desafio) > > Referência de `POST /v1/three-ds/challenge-result`. > [card] [SDK de segurança](/guias/3d-secure/sdk) > > O mesmo fluxo com menos código. > [card] [3D Secure: visão geral](/guias/3d-secure/visao-geral) > > Estados, ECI e comparativo. # 3D Secure: visão geral Source: https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral O que é a autenticação 3D Secure, as três formas de integrar na Finvia e como escolher entre elas. O 3D Secure (3DS) é uma etapa de autenticação do titular do cartão feita pelo banco emissor durante a compra online. Antes de a cobrança ser processada, o banco confere se quem está comprando é mesmo o dono do cartão. Às vezes isso acontece sem o cliente perceber (fluxo sem fricção, *frictionless*); outras vezes o banco pede uma confirmação, como um código enviado por SMS ou uma aprovação no app do banco (desafio, *challenge*). > [!NOTE] > > **Para o negócio:** o 3DS acrescenta uma confirmação do titular do cartão na compra. Quando a configuração da sua conta exige 3DS, a cobrança de cartão só segue com a autenticação bem-sucedida (`state` `success`); sem ela, a cobrança é recusada. Converse com o time Finvia para saber se o 3DS é exigido no seu perfil. ## Quando usar | Situação | Recomendação | | - | - | | A configuração da sua conta exige 3DS | Integre uma das três formas desta página. Sem 3DS, a cobrança é recusada com `3ds_required` | | Checkout web com cartão digitado ou cartão salvo | Qualquer uma das três formas | | Apple Pay | Não se aplica: a autenticação já vem no token | | Pix | Não se aplica: o 3DS é só para cartão | ## Termos que aparecem nesta seção | Termo | O que é | | - | - | | Emissor / ACS | O banco que emitiu o cartão e o servidor dele que autentica o titular (ACS) | | Fingerprinting | Coleta de dados do navegador do cliente, feita em um iframe oculto, para o emissor avaliar o risco | | Frictionless | Autenticação aprovada sem interação do cliente | | Challenge (desafio) | O emissor pede uma confirmação ao cliente, em uma janela visível | | Criptograma (`cryptogram`) | Valor de autenticação (CAVV) gerado quando a autenticação dá certo | | ECI | Electronic Commerce Indicator, código que indica o resultado da autenticação | O desenho abaixo mostra o caminho de uma autenticação 3DS, com e sem desafio, e o que acontece com a cobrança em cada resultado. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI["Envio do cartão e dos
dados do navegador"]:::lojista ACS["Banco emissor (ACS)
avalia o risco"]:::externo Q1{"O emissor pede
confirmação?"}:::decisao CH["Desafio (challenge)
código por SMS ou
aprovação no app do banco"]:::alerta SUC(["state success
com cryptogram e eci"]):::ok OUT(["Outro state
failure, unenrolled, error..."]):::erro Q3{"3DS obrigatório
na sua conta?"}:::decisao SEGUE(["Cobrança segue
normalmente"]):::ok REC(["Cobrança recusada
reason começa com 3ds_"]):::erro INI -->|"fingerprinting em iframe
oculto, se o emissor pedir"| ACS ACS --> Q1 Q1 ==>|"não: sem atrito
(frictionless)"| SUC Q1 -->|"sim"| CH CH -->|"titular confirmou"| SUC CH -->|"não confirmou"| OUT ACS -.->|"cartão não inscrito
ou erro"| OUT SUC ==> SEGUE OUT --> Q3 Q3 -->|"sim"| REC Q3 -->|"não, dados repassados
sem validação"| SEGUE classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 ``` O fingerprinting e o desafio só acontecem quando o emissor pede. No 3DS gerenciado, a página da Finvia conduz essas telas. No SDK, o próprio SDK faz isso dentro do seu checkout. No 3DS via API, quem exibe os iframes é o seu checkout. ## As três formas de integrar > [card] [3DS gerenciado](/guias/3d-secure/gerenciado) > > Você cria a cobrança com `threeDSMode: "managed"`, abre a `authenticationUrl` para o comprador e acompanha o resultado. > [card] [SDK de segurança](/guias/3d-secure/sdk) > > Um SDK no front-end faz a autenticação completa e devolve o resultado para a cobrança. > [card] [3DS via API](/guias/3d-secure/via-api) > > Você conduz cada etapa pelas rotas de 3DS e monta o objeto `threeDS`. ### Como cada forma funciona **3DS gerenciado.** Você cria a cobrança normalmente, com `paymentMethod.threeDSMode` `managed` e o objeto `browser` com os dados do navegador. Se o banco aprova sem interação, a resposta já traz o status final. Se o banco pede verificação ou desafio, a cobrança fica em `authentication_required` e a resposta traz a `authenticationUrl`, que você abre para o comprador (modal, iframe ou nova aba). A página da Finvia conduz a autenticação e conclui a cobrança, e o resultado chega pelos webhooks ou por `GET /v1/charges/{id}`. O comprador não volta automaticamente para a loja ao final. **SDK de segurança.** No seu checkout, o SDK `@fastpaybr/security-sdk` (publicado com o nome anterior da marca) faz o fluxo inteiro com o método `process()`: coleta de dados do navegador, desafio em um modal quando o emissor pede, e resultado final. Você envia esse resultado no campo `paymentMethod.threeDS` de `POST /v1/charges`. **3DS via API (BYO, *bring your own*).** Você chama as rotas de 3DS uma a uma (`POST /v1/three-ds/authenticate`, `submit`, `challenge-result`), exibe os iframes de fingerprinting e de desafio no seu front-end e monta o objeto `threeDS` para a cobrança. ### Comparativo | | 3DS gerenciado | SDK de segurança | 3DS via API | | - | - | - | - | | Esforço de integração | Menor: abrir a `authenticationUrl` e acompanhar o resultado por webhook ou consulta | Baixo: instalar o SDK e chamar `process()` | Maior: você controla iframes, `postMessage` e cada chamada | | Controle da experiência | Menor | Médio: modal configurável ou container próprio | Total | | Quando a cobrança é criada | Antes da autenticação | Depois da autenticação | Depois da autenticação | | Onde vai o resultado | A página de autenticação retoma a cobrança; você recebe o resultado por webhook ou `GET /v1/charges/{id}` | `paymentMethod.threeDS` em `POST /v1/charges` | `paymentMethod.threeDS` em `POST /v1/charges` | | Chave usada no front-end | Nenhuma: a página de autenticação já traz o que precisa | Pública (`pk_`) no SDK | Pública (`pk_`) nas rotas de 3DS | | Volta para a loja ao final | Não há | O fluxo roda dentro do seu checkout | O fluxo roda dentro do seu checkout | | Indicado para | Quem quer delegar a condução do 3DS à Finvia | A maioria dos checkouts web | Checkouts com interface própria ou requisitos específicos | > [!TIP] > > **Para o desenvolvedor:** em todas as formas, a cobrança continua sendo criada pelo seu backend com a chave secreta. A chave pública (`pk_`) é usada apenas nas etapas de autenticação que rodam no navegador. Para escolher a forma de integrar, siga as perguntas do desenho abaixo. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Cobrança com cartão
que vai usar 3DS"]):::neutro Q0{"É Pix ou
Apple Pay?"}:::decisao NA["3DS não se aplica"]:::neutro Q1{"Quer delegar à Finvia
as telas do 3DS?"}:::decisao GER["3DS gerenciado
threeDSMode managed
cobrança criada antes"]:::neutro Q2{"Precisa controlar cada
tela e cada chamada?"}:::decisao API["3DS via API
rotas /v1/three-ds/
cobrança criada depois"]:::neutro SDK["SDK de segurança
process() no front-end
cobrança criada depois"]:::neutro INI --> Q0 Q0 -->|"sim"| NA Q0 -->|"não"| Q1 Q1 -->|"sim, e acompanho
por webhook"| GER Q1 -->|"não"| Q2 Q2 -->|"sim"| API Q2 ==>|"não, a maioria
dos checkouts"| SDK classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Nas três formas, a cobrança é criada pelo seu backend com a chave secreta. A diferença está em quem conduz as telas e em que momento a cobrança nasce. ## Resultado da autenticação No SDK e no 3DS via API, o resultado de uma autenticação 3DS é o objeto `threeDS` (schema `CreditCardThreeDS`), que você envia em `POST /v1/charges`. Os campos `type` e `state` são obrigatórios. Nos demais, omita o campo quando não tiver valor e não envie `null`. | Campo | O que é | | - | - | | `type` | Tipo de autenticação (ex.: `full`) | | `state` | Resultado: `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled` | | `cryptogram` | CAVV em Base64. Com `state` `success`, é na prática obrigatório | | `eci` | Electronic Commerce Indicator. Com `state` `success`, é na prática obrigatório | | `version` | Versão do protocolo (ex.: `2.1.0`, `2.2.0`) | | `directoryServerTransactionId` | ID da transação no Directory Server (bandeira) | | `threeDsServerTransactionId` | ID da transação no 3DS Server | | `acsTransactionId` | ID da transação no ACS (emissor) | > [!NOTE] > > O schema também lista `mode`, `deviceData` e `challenge.returnUrl`. Não envie esses campos: `mode` é de uso interno, e `deviceData` e `challenge.returnUrl` não são lidos no 3DS da Finvia. ### Estados (`state`) | Estado | Significado | Ação recomendada | | - | - | - | | `success` | Autenticação bem-sucedida | Prosseguir com a cobrança | | `failure` | O cliente falhou na autenticação | Recusar a transação ou pedir outra forma de pagamento | | `unenrolled` | Cartão não inscrito no 3DS | Avaliar a sua política de risco | | `error` | Erro no processo de autenticação | Tentar de novo ou usar outra forma de pagamento | | `unsupported_brand` | A bandeira não suporta 3DS | Usar outra forma de pagamento | | `disabled` | 3DS desabilitado para este cartão | Avaliar a sua política de risco | > [!WARNING] > > Quando o 3DS é exigido pela configuração da sua conta, só `state` `success` permite que a cobrança siga. Qualquer outro estado leva à recusa. ### ECI | Valor | Significado | | - | - | | `05` | Autenticado | | `06` | Tentativa de autenticação | | `07` | Não autenticado | Esses são os valores comuns citados no contrato. ## O que acontece se o 3DS faltar As validações abaixo só valem quando o 3DS é obrigatório para a sua conta. Nos outros casos, os dados 3DS enviados são repassados sem validação. | Situação | `reason` da cobrança recusada | | - | - | | 3DS não fornecido, ou o 3DS gerenciado não pôde ser feito (sem `browser` ou falha do serviço de 3DS) | `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | | Falha de autenticação | `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card` | | `cryptogram` ou `eci` ausentes ou nulos | `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` | | Autenticação sem sucesso no 3DS gerenciado | `3ds_: Authentication did not succeed` | | Tudo certo | A cobrança segue normalmente | Trecho da resposta de uma cobrança recusada por falta de 3DS: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "refused", "reason": "3ds_required: Não foi possível completar a autenticação 3DS obrigatória" } ``` A recusa vem na resposta da criação da cobrança e também no webhook `charge.refused` (ou `charge.failed`), enviado aos seus endpoints e à `postbackUrl` da cobrança ([Webhooks de cobrança](/guias/webhooks/cobranca)). O texto de `reason` mistura português e inglês e aparece aqui exatamente como a API devolve. Trate pelo prefixo (`3ds_required`, `3ds_failed`, `3ds_incomplete`). ## Perguntas frequentes > [accordion] Qual forma devo escolher? > > Se você quer usar um componente pronto no navegador, que conduz fingerprinting e desafio, use o SDK. Se você quer delegar as telas de autenticação à Finvia e pode acompanhar o resultado por webhook, sem volta automática do comprador para a loja, use o 3DS gerenciado. Se precisa controlar cada tela e cada etapa, use o 3DS via API. > [accordion] Preciso de 3DS no Apple Pay? > > Não. No Apple Pay a autenticação já vem no token, e o 3DS não se aplica. > [accordion] O cliente sempre vê uma tela do banco? > > Não. No fluxo sem fricção (`frictionless`), o emissor aprova sem interação. O desafio (`challenge`) só aparece quando o emissor pede. > [accordion] Posso usar 3DS com cartão salvo? > > Sim. A variante de cartão salvo aceita `threeDSMode`, `browser` e `threeDS`, com as mesmas regras do cartão digitado. ## Como testar O [roteiro de homologação](/homologacao/roteiro) informa que o 3D Secure, quando se aplica ao seu perfil, é coberto em um cenário específico da sua conta. Combine esse cenário com o time Finvia e, nos testes de cartão (**CHG-01** a **CHG-03**), confira também os casos `3ds_required` e de `state` diferente de `success`. ## Veja também > [card] [3DS gerenciado](/guias/3d-secure/gerenciado) > > Fluxo com `threeDSMode` e `resume-3ds`. > [card] [SDK de segurança](/guias/3d-secure/sdk) > > Autenticação completa no front-end. > [card] [3DS via API](/guias/3d-secure/via-api) > > Rotas de autenticação passo a passo. > [card] [Cartão de crédito](/guias/cobrancas/cartao-de-credito) > > Cobrança com cartão digitado. # Ciclo de vida da assinatura Source: https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida Status, retentativa de cobrança, atualização, cancelamento com arrependimento de 7 dias e histórico de cobranças. Depois de criada, a assinatura passa por renovações, eventuais falhas de cobrança e, em algum momento, termina por cancelamento ou expiração. Esta página explica cada etapa, o que a Finvia faz sozinha e o que a sua plataforma precisa controlar. > [!NOTE] > > **Para o negócio:** três regras resumem a operação. Primeiro, quando o cartão é recusado na renovação, a Finvia tenta de novo por alguns dias antes de encerrar a assinatura. Segundo, não há troca de cartão nem de plano: o cliente cancela e assina de novo, com cobrança imediata. Terceiro, pela regra da plataforma, cancelamentos em até 7 dias da criação da assinatura estornam automaticamente tudo o que foi pago; depois disso, não há estorno e o acesso vale até o fim do período pago. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). ## Status da assinatura | Status | Significado | Cobra e renova? | | - | - | - | | `pending_activation` | A primeira cobrança foi recusada ou está em análise. Não tem retentativa automática e não expira sozinha. Se a análise aprovar o pagamento, passa a `active` automaticamente | Não | | `active` | Ativa e em dia. Continua `active` durante as retentativas de cobrança | Sim | | `cancelled` | Cancelada pelo usuário ou pelo sistema | Não | | `expired` | Encerrada: limite de retentativas de cobrança esgotado ou plano chegou ao `endDate` | Não | `cancelled` e `expired` são estados finais. Para o cliente voltar a assinar, crie uma nova assinatura. O desenho abaixo mostra como a assinatura passa de um status para outro e o aviso que acompanha cada mudança. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB S(["POST /v1/subscriptions"]):::neutro PA["pending_activation
aguardando ativação
não cobra nem renova"]:::alerta ACT["active
ativa e em dia, inclusive
durante as retentativas"]:::ok CAN["cancelled
cancelada"]:::erro EXP["expired
encerrada"]:::erro FIM(["Estados finais
para voltar, crie uma
nova assinatura"]):::neutro S -->|"1ª cobrança aprovada
ou início do trial
subscription.activated"| ACT S -->|"1ª cobrança recusada
ou em análise"| PA PA -->|"análise aprovou
subscription.activated"| ACT ACT -->|"cancelamento
subscription.cancelled"| CAN PA -->|"cancelamento
subscription.cancelled"| CAN ACT -->|"retentativas esgotadas
ou endDate do plano
subscription.expired"| EXP CAN -.-> FIM EXP -.-> FIM classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ### Assinatura parada em `pending_activation` A rotina de cobrança só processa assinaturas `active`. Uma assinatura `pending_activation` não é cobrada de novo, não renova e não expira sozinha. Ela só sai desse status em um caso: a primeira cobrança (ou a do trial pago) ficou em análise (`firstCharge.pending: true` ou `trialCharge.pending: true`) e a análise aprovou. Aí ela passa a `active` e chega `subscription.activated`. Se a análise recusar, chega `subscription.payment_failed` e ela continua parada. `PATCH /v1/subscriptions/{id}` também não destrava, porque só aceita assinaturas `active`. Para tentar de novo pela API (por exemplo, com outro cartão), crie uma **nova** assinatura com `POST /v1/subscriptions`. A API não reaproveita a pendente: a nova tem outro `id`. Cancele a pendente com `POST /v1/subscriptions/{id}/cancel` para que ela não fique na listagem; enquanto estiver pendente, ela não cobra nada. ## Como funciona **1. Criação e ativação** A assinatura nasce `active` quando a primeira cobrança é aprovada (ou o trial começa). Se a primeira cobrança é recusada ou fica em análise, ela fica em `pending_activation`. **2. Renovação a cada ciclo** Uma rotina roda às 6h, 12h e 18h (horário de Brasília) e cobra as assinaturas cujo período terminou. Com sucesso, chega `subscription.renewed`. **3. Retentativas em caso de falha** Se a renovação for recusada, as rodadas seguintes tentam de novo. Cada recusa gera `subscription.payment_failed`. **4. Encerramento** A assinatura termina por cancelamento (`cancelled`) ou por expiração (`expired`), quando as tentativas se esgotam ou o plano chega ao `endDate`. ## Ciclo de cobrança e renovação Não há como escolher o dia da cobrança. O ciclo segue estas regras: | Situação | Como funciona | | - | - | | Sem trial | A primeira cobrança acontece na criação, e o ciclo fica ancorado na data e hora da contratação. `currentPeriodEnd` é o início mais 1 semana (`weekly`), 2 semanas (`biweekly`), 1 mês (`monthly`) ou N dias (`custom`) | | Com trial | O primeiro ciclo pago começa quando o trial termina e a cobrança é feita. Essa data passa a ser a referência | | Mensal | O dia de referência é mantido. Uma contratação em 31/01 renova em 28/02 (ou 29/02) e volta para 31/03 | | Renovação | Uma rotina roda às 6h, 12h e 18h (horário de Brasília). A cobrança sai na primeira rodada do **dia seguinte** à data de `currentPeriodEnd` | | Deslocamento | O novo período começa exatamente no fim do anterior. O atraso de algumas horas até a rodada não desloca o ciclo | Exemplo: uma assinatura mensal contratada em 15/01 às 10h30 cobre o período até 15/02 às 10h30. A renovação sai na rodada das 6h de 16/02, e o novo período vai de 15/02 às 10h30 até 15/03 às 10h30. **Em validação (V-34):** o time Finvia ainda confirma a cobrança no "dia seguinte" ao fim do período e o limite de 12 tentativas antes da publicação. ## Retentativa de cobrança Quando a cobrança de renovação é recusada, a Finvia tenta de novo automaticamente: | Regra | Valor | | - | - | | Retentativas no mesmo dia | Nas rodadas seguintes do dia (12h e 18h, horário de Brasília) | | Dias seguintes | Novas tentativas nas três rodadas (6h, 12h e 18h) | | Limite por ciclo | **12 tentativas recusadas** no mesmo ciclo (cerca de 4 dias) | | Aviso a cada falha | Webhook `subscription.payment_failed`, com `failure_reason` | | Ao atingir o limite | A assinatura passa a `expired` e chega `subscription.expired` | | Status durante as tentativas | Continua `active` | | Tentativa sem envio à cobrança (cartão vencido ou indisponível) | Conta para o limite; `charge.charge_id` vem `null` no webhook | Um plano com `endDate` também encerra a assinatura em `expired` quando o período seguinte começaria depois dessa data. O desenho abaixo mostra a renovação de um ciclo, com as novas tentativas quando o cartão é recusado. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB FIM(["currentPeriodEnd
fim do período"]):::neutro COB["Rotina cobra o cartão
rodadas de 6h, 12h e 18h"]:::finvia Q1{"Cobrança
aprovada?"}:::decisao REN[["subscription.renewed"]]:::evento NOV(["Novo período começa
no fim do anterior"]):::ok FAL[["subscription.payment_failed
com failure_reason"]]:::evento Q2{"Chegou a 12 recusas
no ciclo? (V-34)"}:::decisao PRO["Próxima rodada
12h e 18h no mesmo dia,
depois 6h, 12h e 18h"]:::alerta EXP(["expired"]):::erro EVX[["subscription.expired"]]:::evento FIM -->|"1ª rodada do dia seguinte
(em validação, V-34)"| COB COB --> Q1 Q1 -->|"sim"| REN REN --> NOV NOV -.->|"próximo ciclo"| FIM Q1 -->|"não"| FAL FAL --> Q2 Q2 -->|"não: segue active"| PRO PRO --> COB Q2 -->|"sim"| EXP EXP --> EVX classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` O dia seguinte e o limite de 12 tentativas estão em validação (V-34), como indicado acima. > [!NOTE] > > Enquanto houver retentativas pendentes, a assinatura continua `active`. Use o `subscription.payment_failed` para avisar o comprador a atualizar o cartão. Como não existe troca de cartão na assinatura, o caminho é cancelar e criar outra (veja [Trocar cartão ou plano](#trocar-cartão-ou-plano)). > [!NOTE] > > **Para o negócio:** a janela de retentativas é a oportunidade de recuperar o assinante. Uma régua de comunicação comum é avisar na primeira falha ("tivemos um problema com o seu cartão") e reforçar perto do fim das tentativas, com um link para o cliente assinar de novo com outro cartão. ## Atualizar a assinatura Apenas `metadata` pode ser atualizado, e só em assinaturas `active`. ```bash cURL theme={null} curl -X PATCH "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "metadata": { "notes": "Cliente VIP" } }' ``` Resposta `200`: ```json theme={null} { "success": true, "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "metadata": { "notes": "Cliente VIP" } } ``` | Campo atualizável | Tipo | Descrição | | - | - | - | | `metadata` | object | Metadados adicionais da assinatura | ### Trocar cartão ou plano > [!WARNING] > > Não existe troca de cartão, troca de plano, alteração de valor nem pausa. **Para trocar o cartão ou o plano, cancele a assinatura e crie outra.** A nova assinatura começa um ciclo novo, **com cobrança imediata**. **1. Registre o novo cartão (se for troca de cartão)** `POST /v1/cards` com os dados do novo cartão. **2. Cancele a assinatura atual** `POST /v1/subscriptions/{id}/cancel`. Atenção à regra de 7 dias explicada abaixo. **3. Crie a nova assinatura** `POST /v1/subscriptions` com o novo `cardTokenId` ou o novo `subscriptionPlanId`. A primeira cobrança acontece imediatamente. > [!NOTE] > > **Para o negócio:** na troca, o cliente paga a nova assinatura imediatamente, mesmo que ainda tenha dias do período anterior. Se a troca acontece depois de 7 dias da contratação, não há estorno automático da assinatura antiga. Defina a sua política (por exemplo, conceder dias extras ou fazer a troca perto da data de renovação) e comunique ao cliente antes. ## Cancelamento ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "reason": "Cliente solicitou cancelamento" }' ``` O corpo é opcional. O campo `reason` aceita até 500 caracteres. A API trata o cancelamento de duas formas, conforme a data de criação da assinatura. O cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas e vem com `cancellationType` igual a `regret` (arrependimento): | | Arrependimento (`regret`) | Regular (`regular`) | | - | - | - | | Quando | Até 7 dias após a criação (em dias completos) | Depois de 7 dias | | Estorno | **Todas as cobranças pagas** da assinatura são estornadas automaticamente: trial pago, primeira cobrança e renovações dentro do período | Sem estorno | | `refunded` | `true` quando havia cobrança paga e todas foram estornadas; `false` quando não havia o que estornar (ex.: trial grátis) ou quando um estorno não foi concluído | `false` | | Status | `cancelled` | `cancelled` | | Cobranças futuras | Param | Param imediatamente | | Acesso | Encerrado **na hora** | Continua até `accessRevokedAt` (fim do período pago, `current_period_end`). Sua plataforma controla | | Webhook | `subscription.cancelled` com `cancellation_type: "regret"` | `subscription.cancelled` com `cancellation_type: "regular"` e `refunded: false` | O desenho abaixo mostra o que acontece em cada tipo de cancelamento. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB IN(["POST /v1/subscriptions/{id}/cancel"]):::neutro Q{"Até 7 dias completos
da criação?"}:::decisao RG["regret
arrependimento"]:::alerta RG1["Estorna todas as
cobranças pagas
refunded: true se havia"]:::finvia RG2(["Acesso encerrado na hora
bloqueie já"]):::erro RE["regular
depois de 7 dias"]:::neutro RE1["Sem estorno
refunded: false
cobranças param"]:::finvia RE2(["Acesso até accessRevokedAt
sua plataforma bloqueia"]):::alerta EV[["status cancelled
subscription.cancelled
com cancellation_type"]]:::evento IN --> Q Q -->|"sim"| RG Q -->|"não"| RE RG --> RG1 --> RG2 RE --> RE1 --> RE2 RG2 --> EV RE2 --> EV classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ### Regra dos 7 dias Regra da plataforma: se a assinatura for cancelada em até 7 dias da criação, todas as cobranças pagas dela são estornadas automaticamente e o acesso é encerrado na hora. Depois desse prazo, o cancelamento não gera estorno e o acesso continua até o fim do período pago. * A regra é automática para todo cancelamento dentro da janela, venha ele do lojista ou da Finvia, por qualquer motivo. Ela não depende de pedido do comprador e vale também para venda entre empresas. * A janela conta a partir da **criação da assinatura**, e não da entrega do produto ou serviço nem da primeira cobrança. * A contagem é em dias completos: um cancelamento feito até 7 dias e 23 horas depois da criação ainda é `regret`. * Não existe opção para cancelar dentro da janela sem estornar. **Em validação (V-51):** o jurídico da Finvia decide se esta página cita a base legal (art. 49 do CDC) e com que ressalva. ### Arrependimento (até 7 dias) ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "cancelled", "cancellationType": "regret", "refunded": true, "refundId": "2RhQg9M7ZCg3X3nMb9W4kA1T", "accessRevokedAt": "2024-01-16T10:30:00.000Z" } ``` `refundId` identifica o estorno (pode ser `null`). `accessRevokedAt` indica quando o acesso foi revogado. > [!WARNING] > > No cancelamento por arrependimento, confira `refunded`. Se vier `false` numa assinatura que tinha cobrança paga, um estorno não foi concluído e o valor ainda não voltou ao cliente. Acompanhe pelo histórico da assinatura ou acione o suporte da Finvia. ### Cancelamento regular (depois de 7 dias) ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "cancelled", "cancellationType": "regular", "refunded": false, "accessRevokedAt": "2024-02-15T10:30:00.000Z" } ``` No cancelamento regular, `accessRevokedAt` é só a **data até a qual o acesso do comprador vale** (fim do período já pago). O status já é `cancelled` e as cobranças pararam. É a **sua plataforma** que mantém o acesso até essa data e o encerra depois. > [!TIP] > > **Para o desenvolvedor:** ao receber a resposta do cancelamento (ou o webhook `subscription.cancelled`), grave `accessRevokedAt` no seu sistema e agende o bloqueio do acesso para essa data. No caso `regret`, bloqueie imediatamente. ## Histórico de cobranças A consulta da assinatura por ID traz o histórico de tentativas de cobrança em `charges`. Há uma linha por tentativa: as retentativas recusadas de um ciclo repetem o mesmo `billingCycle`. A lista vem ordenada por `billingCycle` decrescente, e `billingCycle: 0` é a cobrança do trial pago. ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "active", "currentPeriodStart": "2024-01-15T10:30:00.000Z", "currentPeriodEnd": "2024-02-15T10:30:00.000Z", "cancelledAt": null, "cancellationType": null, "refunded": false, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z", "plan": { "id": "2RhQg9M7ZCg3X3nMb9W2kY9R", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly" }, "customer": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "name": "Joao Silva", "email": "joao@email.com" }, "merchant": { "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "tradeName": "Loja Exemplo" }, "charges": [ { "id": "2RhQg9M7ZCg3X3nMb9W3kZ0S", "billingCycle": 1, "billingPeriodStart": "2024-01-15T10:30:00.000Z", "billingPeriodEnd": "2024-02-15T10:30:00.000Z", "amount": 99.90, "currency": "BRL", "status": "paid", "pspTransactionId": "12345", "failureReason": null, "createdAt": "2024-01-15T10:30:00.000Z" } ], "metadata": { "referralCode": "PROMO2024" } } ``` ### Status das cobranças da assinatura | Status | Significado | | - | - | | `pending` | Em análise | | `paid` | Paga com sucesso | | `failed` | Falhou (o motivo vem em `failureReason`) | | `refunded` | Estornada | > [!NOTE] > > `charges[].id` é o id do **registro de cobrança da assinatura** (igual a `data.charge.id` nos webhooks de assinatura) e não funciona em `GET /v1/charges/{id}`. O id da cobrança vem em `firstCharge.chargeId` e `trialCharge.chargeId` na criação, em `data.charge.charge_id` nos webhooks e em `data[].chargeId` na listagem de cobranças do plano (`GET /v1/subscription-plans/{id}/charges`), que traz também `id`, `subscriptionId` e `billingCycle`. Veja [Consultar assinatura](/referencia/assinaturas/consultar). ### Listar assinaturas `GET /v1/subscriptions` é paginada e aceita os filtros `merchantId`, `customerId`, `status` (`pending_activation`, `active`, `cancelled`, `expired`), `search` (nome ou e-mail do cliente, ou nome do plano), `page` (padrão `1`) e `size` (padrão `10`). ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions?customerId=2vorkDcXyvzifL63YX09S9VqcnI&status=active" \ -u "$FINVIA_API_KEY:" ``` > [!TIP] > > **Para o desenvolvedor:** antes de criar uma assinatura, consulte se o cliente já tem uma `active` no mesmo plano com `GET /v1/subscriptions?customerId=...&status=active`. Isso evita assinaturas duplicadas quando o cliente clica duas vezes ou volta ao checkout. ## Webhooks do ciclo de vida | Evento | Quando | | - | - | | `subscription.created` | Nova assinatura criada | | `subscription.activated` | Primeira cobrança bem-sucedida (em planos com trial, inclui a ativação em trial) | | `subscription.renewed` | Cobrança recorrente processada (inclui a primeira cobrança cheia após o trial) | | `subscription.payment_failed` | Falha na cobrança recorrente (um por tentativa) | | `subscription.cancelled` | Assinatura cancelada | | `subscription.expired` | Assinatura encerrada (limite de retentativas ou fim do plano) | Cada cobrança de assinatura paga também dispara `charge.created` e `charge.paid`. A recusa de uma cobrança de assinatura **não** dispara webhook `charge.*` de recusa: quem avisa é o `subscription.payment_failed`. Payloads completos em [Webhooks de assinatura](/guias/webhooks/assinatura). ## Boas práticas 1. **Valide o plano antes do checkout.** Consulte `GET /v1/subscription-plans/{id}` e confirme que o plano está `active`. 2. **Trate falha na primeira cobrança.** Se a resposta da criação vier com `status: "pending_activation"` e `firstCharge.success: false`, ofereça ao cliente tentar de novo com outro cartão, criando uma nova assinatura, e cancele a pendente. 3. **Não duplique em caso de análise.** Se `firstCharge.pending` vier `true`, o pagamento está em análise. Não crie outra assinatura: aguarde `subscription.activated` (aprovado) ou `subscription.payment_failed` (recusado). 4. **Avise o cliente sobre a renovação.** Envie um lembrete alguns dias antes da cobrança automática. 5. **Trate cartão vencido ou recusado.** A cada tentativa que falha chega `subscription.payment_failed`. Oriente o cliente a cancelar e criar outra assinatura com o novo cartão. 6. **Use `metadata`.** Guarde dados que ligam a assinatura ao seu sistema: ```json theme={null} { "metadata": { "referralCode": "PROMO2024", "campaignId": "black-friday", "internalUserId": "12345" } } ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` `Only active subscriptions can be updated` | Tentativa de atualizar assinatura que não está `active` | Só atualize `metadata` de assinaturas ativas | | `400` `Subscription already cancelled or expired` | Cancelamento de assinatura já encerrada | Consulte o status antes de cancelar | | `404` `Subscription not found` | `id` incorreto | Confira o `id` com a listagem | | Cliente perdeu o acesso antes do fim do período | Acesso bloqueado no momento do cancelamento `regular` | Mantenha o acesso até `accessRevokedAt` | | Cliente com acesso depois de cancelar em até 7 dias | Acesso não revogado no cancelamento `regret` | No `regret`, revogue imediatamente | | Tentativa de trocar cartão via `PATCH` | Só `metadata` é atualizável | Cancele e crie nova assinatura | | Assinatura `pending_activation` não é cobrada de novo | Não há retentativa da primeira cobrança | Crie uma nova assinatura com outro cartão e cancele a pendente | | `GET /v1/charges/{id}` não encontra a cobrança de um ciclo | Foi usado `charges[].id`, que é o registro da assinatura | Use o `chargeId` (veja [Histórico de cobranças](#histórico-de-cobranças)) | ## Perguntas frequentes > [accordion] Quantas vezes a Finvia tenta cobrar um cartão recusado? > > Hoje, até 12 tentativas recusadas no mesmo ciclo, nas rodadas das 6h, 12h e 18h (horário de Brasília), ao longo de cerca de 4 dias. No limite, a assinatura passa a `expired` e chega `subscription.expired`. > [accordion] Posso pausar uma assinatura? > > Não. Não há pausa. A alternativa é cancelar e, quando o cliente quiser voltar, criar uma nova assinatura. > [accordion] O cliente cancelou no 5º dia. O que acontece com o dinheiro? > > Pela regra da plataforma, é um cancelamento por arrependimento (`regret`): todas as cobranças pagas são estornadas automaticamente e o acesso é encerrado na hora. Confira `refunded: true` na resposta. > [accordion] O cliente cancelou no 20º dia de um plano mensal. Ele perde o acesso imediatamente? > > Não deveria. O status vira `cancelled` e as cobranças param, mas o acesso vale até `accessRevokedAt`, o fim do período já pago. Quem controla isso é a sua plataforma. > [accordion] Assinatura expirada pode ser reativada? > > Não. `expired` é um estado final. Crie uma nova assinatura para o cliente. ## Como testar | Código | Cenário | O que comprovar | | - | - | - | | SUB-04 | Criar assinatura | Status `active` e primeira cobrança processada | | SUB-05 | Webhooks de criação e ativação | Eventos recebidos e respondidos com HTTP 2xx | | SUB-06 | Cancelar em até 7 dias | `cancellationType: "regret"`, `refunded: true` e webhook `subscription.cancelled` | ## Veja também > [card] [Assinaturas: visão geral](/guias/assinaturas/visao-geral) > > Como criar assinaturas. > [card] [Planos](/guias/assinaturas/planos) > > Preço, recorrência e trial. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Payloads de cada evento. > [card] [Cancelar assinatura](/referencia/assinaturas/cancelar) > > Contrato completo da rota. # Planos de assinatura Source: https://docs.fastpaybrasil.com/guias/assinaturas/planos Defina preço, periodicidade e período de teste dos planos que os seus clientes vão assinar. O plano é o "produto" da assinatura: diz quanto custa, em que moeda e de quanto em quanto tempo o cliente é cobrado. Cada assinatura nasce de um plano. Um mesmo plano atende quantos assinantes você tiver. > [!NOTE] > > **Para o negócio:** o time comercial ou de produto define os planos (ex.: Básico mensal R\$ 49,90, Premium mensal R\$ 99,90, Anual com desconto) e o time técnico os cadastra uma vez. Alterar o preço de um plano vale só para quem assinar depois: os assinantes atuais continuam com o preço contratado. Para mudar o preço de quem já assina, é preciso cancelar a assinatura e criar outra. ## Quando usar | Situação | O que fazer | | - | - | | Lançar um novo plano | Criar o plano com `POST /v1/subscription-plans` | | Oferecer período de teste | Configurar `trial` no plano (grátis ou pago) | | Mudar o preço para novos clientes | Atualizar com `PUT /v1/subscription-plans/{id}` | | Parar de vender um plano sem afetar quem já assina | Desativar com `PATCH /v1/subscription-plans/{id}/status` e confirmar | | Campanha com prazo de término | Usar `endDate` no plano | | Mostrar o plano na página de vendas | Enviar uma imagem com `POST /v1/subscription-plans/{id}/image` | ## Como funciona **1. Crie o plano** Defina nome, preço, moeda `BRL`, recorrência e, se quiser, trial e mensagem ao comprador. **2. Opcional: envie a imagem** A imagem aparece em `imageUrl` nas consultas do plano. **3. Use o plano nas assinaturas** Envie o `id` do plano em `subscriptionPlanId` ao criar cada assinatura. **4. Ajuste ou desative quando precisar** Atualizações e desativação afetam só as novas assinaturas. ## Regras de negócio | Regra | Detalhe | | - | - | | Campos obrigatórios | `merchantId`, `name`, `price`, `currency`, `recurrenceType` | | Moeda | Planos cobrados no cartão aceitam apenas `BRL` | | Valor | Em reais: `99.9` significa R\$ 99,90 | | Status inicial | `active` por padrão | | Atualização | **Não** afeta assinaturas existentes. Preço e periodicidade ficam congelados na assinatura no momento da contratação; editar o plano só vale para assinaturas novas | | Desativação | **Não** afeta assinaturas existentes. Só impede novas assinaturas no plano | | Confirmação | Desativar sempre exige confirmação com um token válido por 5 minutos e de uso único | | Permissão | Criar exige a permissão criar assinaturas; consultar e listar, visualizar assinaturas; atualizar, enviar imagem e mudar o status, atualizar assinaturas. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Trial | De 1 a 365 dias, grátis ou pago | > [!WARNING] > > Mudar o preço de um plano **não** reajusta os assinantes atuais. Se a sua estratégia é reajustar a base, o caminho é cancelar a assinatura de cada cliente e criar uma nova no plano atualizado, com nova cobrança imediata. Planeje a comunicação com o cliente antes. ## Tipos de recorrência | `recurrenceType` | Cobrança | | - | - | | `weekly` | Semanal | | `biweekly` | Quinzenal | | `monthly` | Mensal | | `custom` | Intervalo personalizado, em dias, definido em `recurrenceInterval` | Para recorrência personalizada, informe `recurrenceInterval` **em dias**: ```json theme={null} { "recurrenceType": "custom", "recurrenceInterval": 90 } ``` Esse plano cobra a cada 90 dias. > [!WARNING] > > O intervalo `custom` conta **dias corridos**. `custom` com `30` não é igual a `monthly`: o mensal mantém o dia do mês da contratação, e o `custom` só soma dias, então a data da cobrança desliza conforme o calendário. Da mesma forma, "a cada 60 dias" não é "bimestral no mesmo dia do mês". Se o cliente espera ser cobrado sempre no mesmo dia do mês, use `monthly`. Nos tipos `weekly`, `biweekly` e `monthly`, `recurrenceInterval` é ignorado. ## Trial (período de teste) O plano pode ter um período de teste, grátis ou pago, configurado no objeto `trial`: ```json theme={null} { "trial": { "durationDays": 14, "isFree": true } } ``` | Campo | Tipo | Descrição | | - | - | - | | `durationDays` | integer | Duração do trial em dias (mínimo `1`, máximo `365`). Obrigatório no objeto | | `isFree` | boolean | `true` = trial grátis; `false` = trial pago (exige `price`). Obrigatório no objeto | | `price` | number | Valor cobrado no trial. Obrigatório quando `isFree` é `false` | ### Como cada caso se comporta na criação da assinatura | Caso | Cobrança na criação | Validação do cartão | | - | - | - | | **Trial grátis** (`isFree: true`) | Nenhum valor de mensalidade | A Finvia cobra **R\$ 1,00** e estorna em seguida | | **Trial pago** (`isFree: false`) | O valor do trial (`trial.price`), imediatamente | A própria cobrança valida o cartão | | **Sem trial** | A primeira cobrança cheia, imediatamente | A própria cobrança valida o cartão | | **`skipTrial: true`** na assinatura | O valor cheio, imediatamente, ignorando o trial do plano | A própria cobrança valida o cartão | O desenho abaixo mostra o caminho de cada caso, da criação da assinatura até a primeira cobrança cheia. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB IN(["POST /v1/subscriptions"]):::neutro Q1{"skipTrial: true?"}:::decisao Q2{"O plano
tem trial?"}:::decisao Q3{"Trial grátis
isFree: true?"}:::decisao CHE["Cobra o valor cheio
na criação"]:::finvia VAL["Cobra R$ 1,00 e estorna
para validar o cartão
sem webhook"]:::finvia PAG["Cobra trial.price
na criação"]:::finvia E422["422 CARD_VALIDATION_FAILED
nada é criado"]:::erro A1[["subscription.activated"]]:::evento A2[["subscription.activated
com o objeto trial"]]:::evento TRI["Período de trial
durationDays: 1 a 365"]:::alerta FIM["Fim do trial
primeira cobrança cheia"]:::finvia R2[["subscription.renewed
com o objeto trial"]]:::evento C1(["Ciclo ancorado
na contratação"]):::ok C2(["Ciclo ancorado
no fim do trial"]):::ok PEN(["pending_activation
veja Ciclo de vida"]):::erro IN --> Q1 Q1 -->|"sim"| CHE Q1 -->|"não"| Q2 Q2 -->|"não"| CHE Q2 -->|"sim"| Q3 Q3 -->|"sim"| VAL Q3 -->|"não, trial pago"| PAG VAL -->|"recusada, em análise
ou sem resposta"| E422 VAL -->|"aprovada"| A2 PAG -->|"aprovada"| A2 CHE -->|"aprovada"| A1 A1 --> C1 A2 --> TRI TRI --> FIM FIM -->|"aprovada"| R2 R2 --> C2 PAG -->|"recusada ou
em análise"| PEN CHE -->|"recusada ou
em análise"| PEN classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Ao fim do trial, a primeira cobrança cheia é processada no ciclo normal. Em planos com trial, a ativação e a primeira cobrança cheia geram os webhooks `subscription.activated` e `subscription.renewed`, com o objeto `trial` no payload. ### Validação de R\$ 1,00 no trial grátis > [!WARNING] > > No trial grátis, o comprador pode ver **duas linhas na fatura**: a cobrança de R\$ 1,00 e o estorno. **Avise-o no checkout** (por exemplo: "Para validar o seu cartão, faremos uma cobrança de R\$ 1,00 que será estornada em seguida"). * A validação só acontece em plano com trial grátis, quando a assinatura é criada sem `skipTrial: true`. O estorno do R\$ 1,00 é assíncrono. * Se a validação for **recusada, ficar em análise ou o processador não responder**, a resposta é `422` com `{ "code": "CARD_VALIDATION_FAILED", "message": "Não foi possível validar o cartão: " }`, e nada é criado: nem assinatura, nem webhook. Se ficou em análise, oriente o comprador a usar outro cartão. * `409 CARD_VALIDATION_IN_PROGRESS`: já há uma validação do mesmo cartão em andamento (requisição repetida em paralelo). * `429 CARD_VALIDATION_RATE_LIMITED`: 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na mesma conta em 1 hora. * Os três erros vêm no formato `{ code, message }`. Decida o fluxo pelo `code` e use a `message` só para exibir. * Se a mesma requisição (mesmo merchant, cliente, cartão e plano) for reenviada em até **15 minutos**, a API reaproveita a validação aprovada e não cobra o R\$ 1,00 de novo. A resposta `201` traz `cardValidation: { "validated": true, "amount": 1 }`. * A cobrança de validação e o estorno dela **não geram webhooks**. > [!TIP] > > **Para o desenvolvedor:** se a criação falhar por outro motivo depois da validação (por exemplo, um erro de rede na sua aplicação), repita a mesma requisição dentro de 15 minutos. Assim o cliente não é cobrado de novo pela validação. ## Status do plano | Status | Significado | | - | - | | `active` | Plano disponível para novas assinaturas | | `inactive` | Plano indisponível para novas assinaturas | Desativar um plano não afeta as assinaturas existentes, que continuam sendo cobradas normalmente. O desenho abaixo mostra como o plano muda de status, com a confirmação que a desativação sempre exige. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB NOVO(["Plano criado
/v1/subscription-plans"]):::neutro ACT["active
aceita novas assinaturas"]:::ok TOK["requiresConfirmation: true
confirmationToken
vale 5 min, uso único"]:::alerta INA["inactive
não aceita novas assinaturas"]:::neutro E400["400 Invalid or expired
confirmation token
o plano segue active"]:::erro EXI(["Assinaturas existentes
continuam renovando"]):::ok E404["Nova assinatura no plano
404 Subscription plan
not found or inactive"]:::erro NOVO -->|"padrão"| ACT NOVO -.->|"criado com
status: inactive"| INA ACT -->|"1. PATCH .../status
status: inactive"| TOK TOK -->|"2. PATCH .../status/confirm
em até 5 min · 204"| INA TOK -.->|"token errado,
vencido ou já usado"| E400 INA -->|"PATCH .../status
status: active, na hora"| ACT INA -.-> EXI INA -.-> E404 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ## Passo a passo ### 1. Criar o plano ```http REST (JSON) theme={null} POST /v1/subscription-plans HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card" ], "status": "active" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name": "Plano Premium Mensal", "price": 99.90, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": ["credit_card"], "status": "active" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/subscription-plans', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ merchantId: '36OO3bcGjhPjjF3tzrqOGcmQuKo', name: 'Plano Premium Mensal', price: 99.9, currency: 'BRL', recurrenceType: 'monthly', buyerMessage: 'Bem-vindo ao Plano Premium!', paymentMethods: ['credit_card'], }), }); const { id } = await response.json(); // a resposta 201 traz só o id ``` ```python Python theme={null} import os import requests payload = { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card", ], "status": "active", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/subscription-plans", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '36OO3bcGjhPjjF3tzrqOGcmQuKo', 'name' => 'Plano Premium Mensal', 'price' => 99.9, 'currency' => 'BRL', 'recurrenceType' => 'monthly', 'buyerMessage' => 'Bem-vindo ao Plano Premium!', 'paymentMethods' => [ 'credit_card', ], 'status' => 'active', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscription-plans'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card" ], "status": "active" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card" ], "status": "active" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscription-plans"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card" ], "status": "active" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/subscription-plans", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "merchantId" => "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name" => "Plano Premium Mensal", "price" => 99.9, "currency" => "BRL", "recurrenceType" => "monthly", "buyerMessage" => "Bem-vindo ao Plano Premium!", "paymentMethods" => [ "credit_card", ], "status" => "active", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `merchantId` | string | Sim | ID do merchant dono do plano | | `name` | string | Sim | Nome do plano | | `price` | number | Sim | Preço em reais (ex.: `99.90` = R\$ 99,90) | | `currency` | string | Sim | Código ISO 4217. Para cartão, `BRL` | | `recurrenceType` | string | Sim | `weekly`, `biweekly`, `monthly` ou `custom` | | `recurrenceInterval` | integer | Com `custom` | Intervalo da recorrência personalizada, em dias corridos (inteiro maior que zero). Ex.: `90` | | `endDate` | string (date) | Não | Data de término do plano (ISO 8601, ex.: `2025-12-31`) | | `buyerMessage` | string | Não | Mensagem exibida ao comprador | | `paymentMethods` | string\[] | Não | Formas de pagamento aceitas (ex.: `["credit_card"]`) | | `trial` | object | Não | Configuração do período de teste | | `status` | string | Não | `active` (padrão) ou `inactive` | A resposta `201` traz só o `id` do plano. Para ver o plano completo, use a [consulta](#2-consultar-e-listar-planos). ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" } ``` Erros específicos da criação: `404 Merchant not found` (o `merchantId` não é de uma conta a que a chave tem acesso), `404 Currency not found` (moeda inexistente) e `400 Invalid payment methods: ...` (método desconhecido em `paymentMethods`). #### Exemplos de planos > [tab] Mensal com trial grátis > > ```json theme={null} > { > "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", > "name": "Plano Básico Mensal", > "price": 49.9, > "currency": "BRL", > "recurrenceType": "monthly", > "paymentMethods": ["credit_card"], > "trial": { "durationDays": 7, "isFree": true } > } > ``` > [tab] Semanal com trial pago > > ```json theme={null} > { > "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", > "name": "Marmitas Fit Semanal", > "price": 189.9, > "currency": "BRL", > "recurrenceType": "weekly", > "paymentMethods": ["credit_card"], > "trial": { "durationDays": 7, "isFree": false, "price": 9.9 } > } > ``` > [tab] Trimestral com data de término > > ```json theme={null} > { > "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", > "name": "Curso Intensivo Trimestral", > "price": 299, > "currency": "BRL", > "recurrenceType": "custom", > "recurrenceInterval": 90, > "endDate": "2025-12-31", > "paymentMethods": ["credit_card"] > } > ``` > > Quando o próximo período começaria depois de `endDate`, a assinatura é encerrada com status `expired`. ### 2. Consultar e listar planos ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "recurrenceInterval": null, "endDate": null, "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": ["credit_card"], "imageUrl": "https://storage.example.com/plans/image.png", "status": "active", "activeSubscriptionsCount": 150, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" } ``` `activeSubscriptionsCount` mostra quantas assinaturas ativas o plano tem, útil para o time de negócio acompanhar a base de cada plano. A listagem `GET /v1/subscription-plans` é paginada e aceita `merchantId`, `status` (`active` ou `inactive`), `page` (padrão `1`) e `size` (padrão `10`). A resposta traz `data` e `meta` (`total`, `page`, `limit`, `totalPages`). ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10" \ -u "$FINVIA_API_KEY:" ``` Existe ainda a listagem de cobranças do plano, `GET /v1/subscription-plans/{id}/charges`. Cada item traz `id` (o registro de cobrança da assinatura), `chargeId` (o id da cobrança, usado em `GET /v1/charges/{id}`), `subscriptionId` e `billingCycle`. É o caminho para relacionar o histórico de [Consultar assinatura](/referencia/assinaturas/consultar) às cobranças. `chargeId` vem `null` quando a tentativa nem chegou ao processador. > [!TIP] > > **Para o desenvolvedor:** antes de levar o cliente ao checkout, consulte o plano e confirme que `status` é `active`. Um plano inativo faz a criação da assinatura falhar com `404` `Subscription plan not found or inactive`. ### 3. Enviar a imagem do plano A imagem é enviada como arquivo (`multipart/form-data`, campo `file`), em PNG, JPG ou JPEG. A resposta é `204`, sem corpo. ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image" \ -u "$FINVIA_API_KEY:" \ -F "file=@plano-premium.png" ``` Depois do envio, a URL da imagem aparece em `imageUrl` na consulta do plano. ### 4. Atualizar o plano `PUT /v1/subscription-plans/{id}` exige `merchantId` e aceita os demais campos que você quer mudar: `name`, `price`, `currency`, `recurrenceType`, `recurrenceInterval`, `endDate`, `buyerMessage`, `paymentMethods` e `trial`. Para remover o trial, envie `"trial": null`. ```bash cURL theme={null} curl -X PUT "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "name": "Plano Premium Atualizado", "price": 119.9 }' ``` A resposta `200` traz só o `id` do plano. Para conferir as alterações, consulte o plano. As mudanças valem **só para novas assinaturas**. ### 5. Desativar o plano A desativação é feita em duas etapas. A primeira chamada **sempre** pede confirmação, tenha o plano assinaturas ativas ou não. Essa rota nunca devolve o objeto do plano. **1. Solicite a desativação** ```bash cURL theme={null} curl -X PATCH "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{"status": "inactive"}' ``` Resposta: ```json theme={null} { "requiresConfirmation": true, "confirmationToken": "abc123xyz" } ``` O token vale 5 minutos e é de uso único. Pedir a desativação de novo gera outro token e invalida o anterior. **2. Confirme em até 5 minutos** ```bash cURL theme={null} curl -X PATCH "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{"confirmationToken": "abc123xyz"}' ``` Resposta `204`, sem corpo. O plano fica `inactive`. Token errado, vencido ou já usado: `400 Invalid or expired confirmation token`. Plano inexistente ou de outra conta: `404 Subscription plan not found`. > [!NOTE] > > **Para o negócio:** a confirmação existe para evitar desativações por engano. Se a sua equipe opera planos por um painel interno, mostre a quantidade de assinaturas ativas (`activeSubscriptionsCount`, na consulta do plano) antes de confirmar. Lembre que desativar não cancela ninguém: os assinantes atuais continuam renovando normalmente. Para encerrá-los, é preciso cancelar uma a uma. Para **reativar**, envie `"status": "active"` para a mesma rota. A resposta é `{ "requiresConfirmation": false }` e o plano é ativado imediatamente. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` `Invalid or expired confirmation token` | Token errado, já usado, substituído por um pedido mais recente ou confirmação depois de 5 minutos | Solicite a desativação de novo e confirme em seguida | | `404` `Subscription plan not found` | `id` do plano incorreto | Confira o `id` com a listagem | | Assinantes antigos continuam pagando o preço anterior | A atualização do plano não afeta assinaturas existentes | Comportamento esperado. Para reajustar, cancele e crie nova assinatura | | `422 CARD_VALIDATION_FAILED` na assinatura | Validação de R\$ 1,00 do trial grátis recusada, em análise ou sem resposta do processador | Peça outro cartão ao comprador | | `404` `Merchant not found` ou `Currency not found` ao criar | `merchantId` sem acesso pela chave, ou moeda inexistente | Confira o `merchantId` e use `BRL` | | `400` `Invalid payment methods` ao criar | Método desconhecido em `paymentMethods` | Envie só métodos válidos, como `credit_card` | | Cobrança em data diferente da esperada no plano `custom` | O intervalo conta dias corridos | Ajuste a comunicação ou use `monthly` | | `403` `Acesso negado` | O usuário que gerou a chave não tem a permissão da rota | Gere a chave com Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | ## Perguntas frequentes > [accordion] Posso ter vários planos ativos ao mesmo tempo? > > Sim. Cada plano é independente e cada assinatura aponta para um plano. > [accordion] Mudei o preço do plano. O que acontece com quem já assina? > > Nada. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Só novas assinaturas usam o preço atualizado. > [accordion] Desativar um plano cancela as assinaturas? > > Não. As assinaturas existentes continuam ativas e renovando normalmente. O plano só deixa de aceitar novas assinaturas. Para encerrar as assinaturas, cancele uma a uma. > [accordion] O cliente vai ver a cobrança de R\$ 1,00 do trial grátis? > > Pode ver duas linhas na fatura: a cobrança e o estorno. A documentação orienta avisar o comprador no checkout. > [accordion] Posso dar trial só para alguns clientes? > > O trial é configurado no plano. Para um cliente específico pular o trial, crie a assinatura com `skipTrial: true`, o que cobra o valor cheio imediatamente. Para oferecer trial só a um grupo, crie um plano separado com trial. ## Como testar | Código | Cenário | O que comprovar | | - | - | - | | SUB-03 | Criar plano em `BRL` | Retorna o `id` do plano | | SUB-04 | Criar assinatura no plano | Status `active` e primeira cobrança processada | A criação do plano não movimenta dinheiro. As assinaturas criadas a partir dele são reais mesmo com a chave de teste. ## Veja também > [card] [Assinaturas: visão geral](/guias/assinaturas/visao-geral) > > O fluxo completo da assinatura. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, retentativa e cancelamento. > [card] [Criar plano](/referencia/planos/criar) > > Contrato completo da rota. > [card] [Alterar status do plano](/referencia/planos/alterar-status) > > Ativar e desativar planos. # Assinaturas: visão geral Source: https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral Cobre seus clientes automaticamente a cada semana, quinzena, mês ou intervalo definido, com cartão de crédito. As assinaturas cobram o cartão do cliente automaticamente, em intervalos regulares, sem que ele precise voltar ao seu site a cada ciclo. Servem para planos mensais de software, clubes de assinatura, mensalidades de cursos, academias e qualquer serviço com cobrança recorrente. > [!NOTE] > > **Para o negócio:** com assinatura, a Finvia cuida da cobrança de cada ciclo e das novas tentativas quando o cartão é recusado, e avisa o seu sistema de cada renovação, falha e cancelamento. O cancelamento em até 7 dias da contratação estorna automaticamente as cobranças pagas (veja [Ciclo de vida](/guias/assinaturas/ciclo-de-vida)). A sua equipe define o plano (preço e periodicidade) e a sua plataforma controla o acesso do assinante a partir dos avisos. > [!WARNING] > > **Assinaturas e cadastro de cartão não têm modo de teste.** Mesmo com a chave de teste (`sk_test_`), as cobranças da assinatura são **reais**, inclusive a validação de R\$ 1,00 do trial grátis. O cadastro do cartão (`POST /v1/cards`) também é real, mas não cobra nada. O cofre é o mesmo para teste e produção: um cartão salvo na homologação funciona com a chave de produção. Para homologar, use um cartão real com valor baixo e cancele a assinatura no mesmo dia: o cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas. Veja o [roteiro de homologação](/homologacao/roteiro). ## Quando usar | Situação | Use assinatura? | | - | - | | Plano mensal de SaaS, clube, academia, curso | Sim | | Cobrança semanal, quinzenal ou a cada N dias | Sim (`weekly`, `biweekly` ou `custom`) | | Período de teste grátis ou pago antes da primeira mensalidade | Sim, com trial no plano | | Recompra rápida em que o cliente está presente | Não. Use [cartão salvo](/guias/cofre-de-cartoes) com CVV | | Cobrança recorrente por Pix | Não documentado. As assinaturas são descritas apenas com cartão de crédito | | Valor diferente a cada ciclo | Não. O preço fica fixo na assinatura no momento da contratação | ### Assinatura ou cartão salvo? | | Assinatura | Cartão salvo | | - | - | - | | Quem inicia a cobrança | A Finvia, automaticamente, a cada ciclo | A sua aplicação, com o cliente presente | | CVV a cada cobrança | Não | Sim, obrigatório | | Valor | Fixo, definido no plano | Livre, definido em cada cobrança | | Retentativa automática em recusa | Sim, nas renovações ([Ciclo de vida](/guias/assinaturas/ciclo-de-vida)). A primeira cobrança não tem retentativa | Não | | Indicado para | Mensalidades e planos | Compra com um clique, recompra | ## As três peças | Peça | O que é | Rota | | - | - | - | | Cliente (customer) | Quem assina. Precisa de e-mail e CPF ou CNPJ | `/v1/customers` | | Plano (subscription plan) | Preço, moeda, periodicidade e trial | `/v1/subscription-plans` | | Assinatura (subscription) | O vínculo entre um cliente, um plano e um cartão | `/v1/subscriptions` | O cartão, guardado no [cofre de cartões](/guias/cofre-de-cartoes), é o meio de pagamento da assinatura. O desenho abaixo mostra como cliente, plano e cartão se juntam na assinatura e o que acontece a cada ciclo. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB subgraph CAD["Criados pela sua aplicação"] CLI["Cliente
/v1/customers
e-mail e CPF ou CNPJ"]:::neutro PLA["Plano
/v1/subscription-plans
preço, BRL, periodicidade"]:::neutro CAR["Cartão no cofre
/v1/cards
já nasce active"]:::neutro end ASS["Assinatura
/v1/subscriptions
preço congelado"]:::finvia CLI -->|"customerId"| ASS PLA -->|"subscriptionPlanId"| ASS CAR -->|"cardTokenId"| ASS ASS ==>|"1ª cobrança aprovada
ou início do trial"| ATV(["active"]):::ok ATV -->|"a cada ciclo"| REN["Finvia cobra o cartão
às 6h, 12h ou 18h
sem CVV"]:::finvia REN -->|"aprovada"| EOK[["subscription.renewed"]]:::evento REN -->|"recusada"| EKO[["subscription.payment_failed
e novas tentativas"]]:::evento EOK -.->|"novo ciclo"| ATV EKO -->|"tentativas esgotadas"| EXP(["expired"]):::erro EOK --> SIS["Sua plataforma controla
o acesso pelos avisos"]:::lojista EKO --> SIS style CAD fill:#F7F9FC,stroke:#D5DCE6 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ## Como funciona O fluxo recomendado é o **cards-first**: o cartão é registrado antes e a assinatura é criada a partir dele. A sequência abaixo mostra o fluxo cards-first de ponta a ponta, com a diferença entre plano com trial grátis e os demais. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Assinante end box rgb(243,245,248) Sua aplicação participant S as Seu servidor participant W as Receptor de webhooks end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant P as Processador do cartão end Note over S,F: Antes, uma vez só: POST /v1/subscription-plans cria o plano C->>S: Escolhe o plano e informa o cartão S->>F: POST /v1/customers F-->>S: id do cliente S->>F: POST /v1/cards F-->>S: id do cartão · active S->>F: POST /v1/subscriptions (subscriptionPlanId, customerId, cardTokenId) alt Trial grátis sem skipTrial F->>P: Cobra R$ 1,00 e estorna (validação do cartão) else Trial pago, sem trial ou skipTrial F->>P: Cobra o valor do trial ou o valor cheio end P-->>F: Resultado F-->>S: 201 · status · firstCharge (ou cardValidation) F-)W: subscription.created e, se ativada, subscription.activated S-->>C: Libera o acesso Note over F,P: Nos ciclos seguintes, a Finvia cobra sozinha e avisa com subscription.renewed ou subscription.payment_failed ``` **1. Crie o cliente** `POST /v1/customers` com nome, e-mail, CPF ou CNPJ. Veja [Clientes](/guias/clientes). **2. Crie o plano** `POST /v1/subscription-plans` com preço, moeda `BRL` e recorrência. Normalmente feito uma vez, na configuração do produto. Veja [Planos](/guias/assinaturas/planos). **3. Registre o cartão** `POST /v1/cards` com os dados do cartão. O cartão já nasce ativo. **4. Crie a assinatura com cardTokenId** `POST /v1/subscriptions` com `subscriptionPlanId`, `customerId` e `cardTokenId`. **5. Primeira cobrança** A primeira cobrança é processada imediatamente (ou o trial começa). Se aprovada, a assinatura fica `active`. **6. Cobranças automáticas** A cada ciclo, a Finvia cobra o cartão e envia os webhooks de renovação ou de falha. > [!NOTE] > > O cartão já nasce **ativo** ao ser registrado. Não existe transação de teste nem etapa de ativação, e o campo `validateCard` é obsoleto e não tem efeito. ## Formas de criar a assinatura A criação combina duas escolhas: como informar o **cartão** e como informar o **cliente**. | Cartão | Cliente | Quando usar | | - | - | - | | `cardTokenId` (cartão já registrado) | `customerId` | Fluxo recomendado (cards-first). Cliente e cartão já existem | | `paymentMethod` (cartão digitado, registrado na mesma chamada) | `customerId` | Cliente já cadastrado, cartão novo | | `paymentMethod` | Objeto `customer` (cria ou localiza pelo e-mail) | Checkout de assinatura em uma única chamada | > [!WARNING] > > Envie `customerId` **ou** `customer`, nunca os dois. Da mesma forma, envie `cardTokenId` **ou** `paymentMethod`. Quando o cartão vai em `paymentMethod`, o cliente precisa ter e-mail e CPF ou CNPJ; com o objeto `customer`, envie `document`. Se já existir um cliente com o mesmo e-mail, vale o documento desse cadastro. > [tab] 1. cardTokenId (recomendado) > > ```bash cURL theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \ > -u "$FINVIA_API_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", > "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", > "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo" > }' > ``` > > O cartão precisa estar `active` e pertencer ao mesmo merchant da chave de API. > [tab] 2. Cartão inline > > ```bash cURL theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \ > -u "$FINVIA_API_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", > "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", > "paymentMethod": { > "number": "1111222233334444", > "holderName": "JOAO SILVA", > "expirationMonth": "12", > "expirationYear": "2028", > "cvv": "123" > } > }' > ``` > > O cartão informado é registrado no cofre e passa a ser o cartão da assinatura. O cliente precisa ter e-mail e CPF ou CNPJ. > [tab] 3. Cliente e cartão inline > > ```bash cURL theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \ > -u "$FINVIA_API_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", > "customer": { > "name": "Joao Silva", > "email": "joao@email.com", > "document": { "type": "cpf", "id": "52998224725" }, > "phoneNumber": "+5511987654321" > }, > "paymentMethod": { > "number": "1111222233334444", > "holderName": "JOAO SILVA", > "expirationMonth": "12", > "expirationYear": "2028", > "cvv": "123" > }, > "metadata": { "referralCode": "PROMO2024" } > }' > ``` > > A API procura um cliente com o mesmo e-mail e, se não encontrar, cria um novo. ### Campos da criação | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `subscriptionPlanId` | string | Sim | ID do plano. O plano precisa estar ativo | | `customerId` | string | Um dos dois | ID de cliente existente | | `customer` | object | Um dos dois | `name` e `email` obrigatórios; `document` com `type` (`cpf` ou `cnpj`) e `id` (11 ou 14 dígitos), obrigatório quando o cartão vai em `paymentMethod`; `phoneNumber` opcional | | `cardTokenId` | string | Um dos dois | ID de cartão já registrado pela mesma conta | | `paymentMethod` | object | Um dos dois | `number`, `holderName`, `expirationMonth` (2 caracteres), `expirationYear` (4 caracteres), `cvv` (mínimo 3) | | `skipTrial` | boolean | Não | `true` pula o trial do plano e cobra o valor cheio imediatamente. Padrão `false` | | `metadata` | object | Não | Dados seus, livres (ex.: código de indicação, ID do usuário no seu sistema) | | `validateCard` | boolean | Não | Obsoleto, sem efeito | > [!NOTE] > > Não há como escolher o dia da cobrança: o ciclo é ancorado na data e hora da contratação (ou no fim do trial). Um `billingDay` enviado é ignorado, sem erro. ### Resposta ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "active", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "currentPeriodStart": "2024-01-15T10:30:00.000Z", "currentPeriodEnd": "2024-02-15T10:30:00.000Z", "firstCharge": { "success": true, "chargeId": "2xKp7QmR4tVw9YzA1bC3dE5fG6h", "nsuOperacao": "123456789", "codigoAutorizacao": "ABC123", "message": "Transaction approved" } } ``` | Campo | Descrição | | - | - | | `id` | ID da assinatura. Guarde para consultar e cancelar | | `status` | `active` ou `pending_activation` | | `cardTokenId` | ID do cartão usado. No cartão inline, é o cartão recém-registrado | | `currentPeriodStart` e `currentPeriodEnd` | Período coberto pela primeira cobrança | | `firstCharge` | Resultado da primeira cobrança: `success`, `pending` (em análise), `chargeId` (id da cobrança, usado em `GET /v1/charges/{id}`), `nsuOperacao` (identificador da operação no processador), `codigoAutorizacao` e `message` | | `trialCharge` | Em plano com trial pago: resultado da cobrança do trial, com os mesmos campos | | `cardValidation` | Em plano com trial grátis: `{ "validated": true, "amount": 1 }` | > [!TIP] > > **Para o desenvolvedor:** guarde o `firstCharge.chargeId`. A [consulta da assinatura](/referencia/assinaturas/consultar) não devolve o id da cobrança: o `charges[].id` de lá é o registro da assinatura. ## O que acontece no checkout O desenho abaixo mostra cada verificação feita na criação da assinatura e o resultado de cada caminho. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB IN(["POST /v1/subscriptions"]):::neutro Q1{"Plano existe
e está ativo?"}:::decisao E404["404 Subscription plan
not found or inactive"]:::erro CLI["Cria ou localiza o cliente
pelo e-mail"]:::finvia Q2{"Cartão veio em
paymentMethod?"}:::decisao REG["Registra o cartão
no cofre"]:::finvia E400["400 Failed to register card
cliente sem e-mail
ou CPF/CNPJ"]:::erro Q3{"Trial grátis
sem skipTrial?"}:::decisao VAL["Cobra R$ 1,00
e estorna em seguida"]:::finvia E422["422 CARD_VALIDATION_FAILED
nada é criado"]:::erro COB["Primeira cobrança imediata
trial pago ou valor cheio"]:::finvia Q5{"Resultado da
cobrança?"}:::decisao ACT(["active
libere o acesso"]):::ok PEN(["pending_activation
peça outro cartão e
crie nova assinatura"]):::erro ANA(["pending_activation
firstCharge.pending: true
aguarde o webhook"]):::alerta IN --> Q1 Q1 -->|"não"| E404 Q1 -->|"sim"| CLI CLI --> Q2 Q2 -->|"sim"| REG Q2 -->|"não, cardTokenId"| Q3 REG -->|"cadastro incompleto"| E400 REG -->|"ok"| Q3 Q3 -->|"sim"| VAL Q3 -->|"não"| COB VAL -->|"recusada, em análise
ou sem resposta"| E422 VAL -->|"aprovada: trial começa"| ACT COB --> Q5 Q5 -->|"aprovada"| ACT Q5 -->|"recusada"| PEN Q5 -->|"em análise"| ANA classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` **1. Validação do plano** O plano é validado. Plano inexistente ou inativo gera `404` com `Subscription plan not found or inactive`. **2. Cliente** O cliente é criado ou localizado pelo e-mail. Se ele já existe, vale o documento do cadastro. **3. Cartão** Com `paymentMethod`, o cartão é registrado no cofre da Finvia e já nasce ativo. Sem e-mail ou sem CPF/CNPJ no cliente, a resposta é `400` com `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador`. **4. Validação do trial grátis** Em plano com **trial grátis** (sem `skipTrial`), a Finvia cobra R\$ 1,00 e estorna em seguida, para validar o cartão. Se a cobrança for recusada, ficar em análise ou o processador não responder, a resposta é `422 CARD_VALIDATION_FAILED` e nada é criado. Reenviar a mesma requisição em até 15 minutos reaproveita uma validação aprovada. **5. Primeira cobrança** A primeira cobrança é feita imediatamente: o valor do trial pago, ou o valor cheio quando não há trial. **6. Gravação** A assinatura é gravada com status `active` se a cobrança for aprovada. ### Primeira cobrança recusada ou em análise | Resposta | Significado | O que fazer | | - | - | - | | `status: "active"` e `firstCharge.success: true` | Cobrança aprovada | Liberar o acesso | | `status: "pending_activation"` e `firstCharge.success: false` | Primeira cobrança recusada | A assinatura não está ativa, não cobra, não renova e não tem retentativa. Peça outro cartão, crie uma nova assinatura (ela terá outro `id`) e cancele a pendente | | `firstCharge.pending: true` | Pagamento em análise | **Não** crie outra assinatura. Aguarde `subscription.activated` (aprovado) ou `subscription.payment_failed` (recusado) | > [!WARNING] > > Com a primeira cobrança em análise, criar uma segunda assinatura para "tentar de novo" pode resultar em duas assinaturas cobrando o mesmo cliente se a análise aprovar a primeira. Aguarde o webhook. ## Ciclo de cobrança * O ciclo fica ancorado na **data e hora da contratação**. Em plano com trial, a referência passa a ser o fim do trial, quando a primeira cobrança cheia é feita. * No mensal, o dia de referência é mantido mesmo em meses mais curtos. * As renovações são feitas por uma rotina que roda às **6h, 12h e 18h (horário de Brasília)**. Se a renovação for recusada, há novas tentativas e, no limite delas, a assinatura passa a `expired`. Os detalhes de status, retentativa, atualização e cancelamento estão em [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida). ## Regras de negócio | Regra | Detalhe | | - | - | | Moeda | Planos cobrados no cartão aceitam só `BRL` | | Cliente | Precisa de e-mail e CPF ou CNPJ quando o cartão é cadastrado. O tipo é deduzido pelos dígitos (11 é CPF, 14 é CNPJ); outro tamanho conta como sem documento | | Cartão | Precisa pertencer ao mesmo merchant da chave. As cobranças da assinatura não pedem CVV | | Preço congelado | Preço e periodicidade ficam congelados na contratação. Editar o plano não muda assinaturas existentes | | Split | As cobranças recorrentes de assinatura não recebem split | | Sem troca | Não há troca de cartão, troca de plano, alteração de valor nem pausa. Para trocar, cancele e crie outra | | Arrependimento | Regra da plataforma: cancelamento em até 7 dias da criação estorna todas as cobranças pagas | | Permissão da chave | Depende do perfil de quem gerou a chave. Veja a tabela abaixo | ### Permissões por perfil A chave de API herda o perfil do usuário que a gerou, e cada rota de planos e assinaturas exige uma permissão. Sem ela, a resposta é `403`: ```json theme={null} { "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 } ``` | Rota | Permissão exigida | | - | - | | `POST /v1/subscriptions` | criar assinaturas | | `GET /v1/subscriptions`, `GET /v1/subscriptions/summary`, `GET /v1/subscriptions/{id}` | visualizar assinaturas | | `PATCH /v1/subscriptions/{id}` | atualizar assinaturas | | `POST /v1/subscriptions/{id}/cancel` | cancelar assinaturas | | `GET /v1/subscription-plans`, `GET /v1/subscription-plans/{id}`, `GET /v1/subscription-plans/{id}/charges` | visualizar assinaturas | | `POST /v1/subscription-plans` | criar assinaturas | | `PUT /v1/subscription-plans/{id}`, `POST /v1/subscription-plans/{id}/image`, `PATCH /v1/subscription-plans/{id}/status`, `PATCH /v1/subscription-plans/{id}/status/confirm` | atualizar assinaturas | | Perfil padrão | Acesso às rotas de planos e assinaturas | | - | - | | Owner, Manager e Operador | Todas | | Visualizador | Só as de leitura (`GET`); nas demais, `403` | | Desenvolvedor e Financeiro | Nenhuma: `403` em todas | | Perfis personalizados | Dependem das permissões marcadas | Para integrar assinaturas, gere a chave com um usuário Owner ou Manager. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `Subscription plan not found or inactive` | Plano inexistente ou inativo | Confira o plano com `GET /v1/subscription-plans/{id}` antes do checkout | | `400` `Failed to create subscription` | Dados inválidos ou falha na criação | Confira se enviou só um entre `customerId` e `customer`, e só um entre `cardTokenId` e `paymentMethod` | | `400` `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 nem 14 dígitos (inclusive um cadastro antigo com o mesmo e-mail) | Use um cliente com e-mail e CPF ou CNPJ, informado por `customerId` | | `422 CARD_VALIDATION_FAILED` | Validação de R\$ 1,00 do trial grátis recusada, em análise ou sem resposta | Peça outro cartão. Veja [Criar assinatura](/referencia/assinaturas/criar) | | `409 CARD_VALIDATION_IN_PROGRESS` ou `429 CARD_VALIDATION_RATE_LIMITED` | Requisição repetida em paralelo, ou recusas demais do mesmo cartão ou da conta | Veja os limites em [Criar assinatura](/referencia/assinaturas/criar) | | `403` `Acesso negado` | O perfil do usuário que gerou a chave não tem a permissão da rota | Veja [Permissões por perfil](#permissões-por-perfil) | | Cobrança real feita com a chave de teste | Assinaturas não têm modo de teste | Use um cartão real com valor baixo e cancele no mesmo dia | | Assinatura em `pending_activation` | Primeira cobrança recusada | Peça outro cartão, crie nova assinatura e cancele a pendente | ## Perguntas frequentes > [accordion] Preciso criar o cliente e o cartão antes? > > Não é obrigatório. É possível criar tudo em uma chamada, com o objeto `customer` e o `paymentMethod`. O fluxo cards-first (cliente e cartão antes) é o recomendado porque separa os erros de cadastro dos erros de cobrança. > [accordion] Posso testar assinaturas no sandbox? > > Não. Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste, inclusive a validação de R\$ 1,00 do trial grátis. Use um cartão real com valor baixo e cancele no mesmo dia: o cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas. > [accordion] Se eu aumentar o preço do plano, os assinantes atuais pagam mais? > > Não. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Só as novas assinaturas usam o novo preço. > [accordion] Posso oferecer assinatura com Pix? > > A documentação descreve assinaturas apenas com cartão de crédito. > [accordion] Como o cliente troca de plano? > > Não existe troca de plano. Cancele a assinatura atual e crie outra no novo plano. A nova começa um ciclo novo, com cobrança imediata. ## Como testar | Código | Cenário | O que comprovar | | - | - | - | | SUB-01 | Registrar cartão | `status: "active"` e `pendingActivation: false` | | SUB-03 | Criar plano em `BRL` | Retorna o `id` do plano | | SUB-04 | Criar assinatura | Status `active` e primeira cobrança processada (cobrança real, mesmo com a chave de teste) | | SUB-05 | Webhooks de criação e ativação | `subscription.created` e `subscription.activated` recebidos | | SUB-06 | Cancelar em até 7 dias | `cancellationType: "regret"` e `refunded: true` | ## Veja também > [card] [Planos](/guias/assinaturas/planos) > > Preço, recorrência, trial e desativação. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, retentativa e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos de cada etapa. > [card] [SaaS e assinaturas](/casos-de-uso/saas-assinaturas) > > Caso de uso completo. # Bloqueio, chargeback e MED Source: https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med O que acontece quando um pagamento é contestado no cartão ou no Pix, como a Finvia avisa você, como enviar a defesa e como tratar cada desfecho. Depois de paga, uma cobrança ainda pode ser contestada. No cartão, o titular pede ao banco emissor que desfaça a compra (chargeback). No Pix, a instituição do pagador pode pedir a devolução pelo MED (Mecanismo Especial de Devolução). Enquanto o caso é analisado, a equipe Finvia pode **bloquear** a cobrança e reter o valor. Esta página explica cada etapa, os avisos que você recebe, como enviar a defesa e como tratar cada desfecho. > [!NOTE] > > **Para o negócio:** o aviso de chargeback ou MED chega **por e-mail**, com os detalhes do caso. A defesa é enviada **respondendo a esse e-mail**, dentro do prazo indicado nele. Pela API, o seu sistema acompanha o bloqueio e o desfecho, mas não envia defesa. Se a disputa for ganha, o bloqueio é retirado e o valor fica com você. Se for perdida, o valor volta ao comprador. ## Conceitos | Termo | O que é | | - | - | | Chargeback | Contestação de uma compra com cartão, aberta pelo banco emissor do cartão a pedido do titular, por meio da bandeira. Chega à Finvia pela adquirente. Existe só no cartão | | Pré-chargeback | Alerta recebido quando o titular contestou a compra **antes** de o chargeback ser formalizado (programas Ethoca e Verifi). A cobrança vai para `pre_chargeback` | | MED | MED (Mecanismo Especial de Devolução) é o mecanismo do Pix, definido pelo Banco Central, que permite à instituição do pagador pedir a devolução de um Pix quando há fundada suspeita de fraude ou falha operacional. Durante a análise, o valor fica bloqueado. Se a contestação for aceita, ele é devolvido ao pagador. Existe só no Pix | | Bloqueio cautelar | Outra ferramenta do Pix, diferente do MED: uma retenção preventiva e curta, feita pela instituição do recebedor quando suspeita de fraude. Na API, usa o mesmo bloqueio da cobrança | | Bloqueio da cobrança | Retenção aplicada pela equipe Finvia a uma cobrança `paid` durante uma disputa. Aparece como `isBlocked: true`, e o `status` continua `paid` | | Defesa | Evidências da venda que você envia para contestar a disputa (comprovante de entrega, nota fiscal, conversa com o cliente) | **Em validação (V-32 e V-53):** compliance revisa a definição do MED, a citação normativa e o texto do fluxo de defesa (MED e chargeback), inclusive o prazo para envio de evidências. ## Quando usar este guia | Situação | O que fazer | | - | - | | Recebeu e-mail de alerta de chargeback ou MED | Reúna as evidências e responda ao e-mail dentro do prazo indicado | | Recebeu `charge.blocked` | Marque o pedido como "em disputa" e segure envios ainda não feitos | | Recebeu `charge.pre_chargeback` | Leia `chargebackAlertRefunded` para saber se o valor já foi devolvido | | O pedido está "em disputa" há dias | Consulte a cobrança: a liberação do bloqueio não gera webhook | | A cobrança foi para `chargeback` ou `refunded` | Registre a perda e siga o seu fluxo de cancelamento | | Você quer devolver o valor por iniciativa própria | Use o [estorno](/guias/estorno) | ## Como você fica sabendo O aviso operacional e o aviso técnico chegam por canais diferentes. | Canal | O que chega | Para quem | | - | - | - | | E-mail | Alerta de chargeback ou de MED, com os detalhes do caso e o prazo para a defesa | O e-mail da conta. No Connect, o e-mail da conta master | | `charge.blocked` (envelope padrão) | Bloqueio da cobrança, com `is_blocked`, `blocked_at` e `blocked_reason` | Endpoints de webhook e `postbackUrl` | | `charge.pre_chargeback` (envelope padrão) | Alerta de pré-chargeback | Endpoints de webhook e `postbackUrl` | | `charge.refunded` (envelope padrão) | Valor devolvido ao comprador (estorno no pré-chargeback, MED aceito ou chargeback revertido do saldo) | Endpoints de webhook e `postbackUrl` | | `charge.updated` (legado, camelCase) | Bloqueio, pré-chargeback e chargeback formalizado (`status: "chargeback"`) | Só a `postbackUrl` | | Nenhum | Liberação do bloqueio | Acompanhe pela consulta da cobrança | Na API não existe status nem evento chamado MED. O MED aparece como bloqueio da cobrança. > [!WARNING] > > O status `chargeback` só é avisado pelo `charge.updated`, que vai **somente à `postbackUrl`**. Os endpoints recebem apenas o `charge.refunded`, e só quando o valor é revertido do saldo. Informe a `postbackUrl` em todas as cobranças de cartão e confirme sempre com `GET /v1/charges/{id}`. ## Como funciona o bloqueio O desenho abaixo mostra como uma contestação chega ao bloqueio da cobrança e quais avisos saem em cada canal. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB PAID(["Cobrança paid"]):::ok MED["Pix: a instituição do
pagador abre o MED"]:::externo CBK["Cartão: o emissor abre
a disputa, que chega
pela adquirente"]:::externo CAU["Pix: bloqueio cautelar
da instituição
do recebedor"]:::externo NOT["A Finvia é notificada"]:::neutro MAIL[["E-mail de alerta
para a conta, com os
detalhes e o prazo"]]:::evento EQ["Equipe Finvia
bloqueia a cobrança"]:::finvia DEF["Você responde ao
e-mail com as evidências,
dentro do prazo"]:::lojista EST["status continua paid
isBlocked: true
blockedAt, blockedReason"]:::alerta SAL["Valor já liquidado vai
do saldo disponível
para o bloqueado"]:::alerta EV[["charge.blocked
endpoints e postbackUrl"]]:::evento UPD[["charge.updated
só na postbackUrl"]]:::evento PAID --> MED PAID --> CBK PAID --> CAU MED --> NOT CBK --> NOT NOT --> MAIL NOT --> EQ CAU -->|"mesmo bloqueio
na API"| EQ MAIL --> DEF EQ --> EST EST --> SAL EST --> EV EST --> UPD classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` A liberação do bloqueio não gera webhook. Veja [Desfechos](#desfechos). **1. Cobrança paga** A cobrança está `paid`. Só cobranças `paid` podem ser bloqueadas. **2. A Finvia é notificada** No Pix, a instituição do pagador abre o MED. No cartão, o emissor abre a disputa e ela chega pela adquirente. Você recebe o alerta por e-mail. **3. A equipe Finvia bloqueia a cobrança** O bloqueio é aplicado pela equipe Finvia (ele não chega automaticamente do banco). A cobrança continua `paid` e passa a ter `isBlocked: true`, `blockedAt` e `blockedReason`. Os endpoints e a `postbackUrl` recebem `charge.blocked`. **4. O valor fica retido** O que a venda já liquidou (o líquido mais as taxas da venda) sai do saldo disponível e vai para o saldo bloqueado. Parcelas que liquidarem enquanto o bloqueio durar também caem no saldo bloqueado. **5. Você envia a defesa** Responda ao e-mail do alerta com as evidências, dentro do prazo indicado. **6. Desfecho** Se a disputa for ganha, o bloqueio é retirado. Se for perdida, o valor volta ao comprador. Veja [Desfechos](#desfechos). ### O que a API mostra durante o bloqueio | Campo na consulta | No envelope padrão | Significado | | - | - | - | | `status` | `status` | Continua `paid` | | `isBlocked` | `is_blocked` | `true` enquanto a cobrança está bloqueada. É o campo que diz se ela está bloqueada | | `blockedAt` | `blocked_at` | Data e hora do bloqueio. Continua preenchido depois da liberação | | `blockedReason` | `blocked_reason` | Texto livre preenchido pela equipe Finvia (pode indicar MED ou chargeback). Pode vir vazio e é apagado na liberação | Para listar as cobranças bloqueadas, use `GET /v1/charges?status=blocked`. ## Defesa Não existe rota de API para enviar defesa de MED ou de chargeback. A defesa é tratada com a equipe Finvia, pelo e-mail do alerta. **1. Leia o e-mail do alerta** Ele traz os detalhes do caso e o prazo para a defesa. No Connect, o e-mail vai para a conta master. **2. Reúna as evidências** Comprovante de entrega, nota fiscal, registro de acesso ao produto digital, conversa com o cliente e qualquer outro documento que mostre que a venda foi legítima e entregue. **3. Responda ao e-mail dentro do prazo** Envie as evidências em resposta ao e-mail do alerta. Uma contestação respondida fora do prazo pode ser perdida mesmo com todas as evidências. Como cada caso é analisado: * **Pix (MED):** a contestação é aberta pela instituição financeira do pagador e analisada pela instituição do recebedor, seguindo as regras do Pix definidas pelo Banco Central. A Finvia encaminha as suas evidências à instituição responsável pela análise. Se a devolução for aceita, o valor volta ao pagador e a cobrança fica `refunded`. Se for recusada, o bloqueio é retirado. * **Cartão (chargeback):** a disputa é aberta pelo banco emissor do cartão, por meio da bandeira, e chega à Finvia pela adquirente. A Finvia reúne as suas evidências e as apresenta à adquirente, que as leva ao emissor. O resultado depende do emissor e segue o fluxo das bandeiras. O desenho abaixo junta a defesa por e-mail e os desfechos possíveis no Pix e no cartão. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB MAIL[["E-mail de alerta
com o prazo da defesa"]]:::evento EVI["Reúna as evidências
entrega, nota fiscal,
conversa com o cliente"]:::lojista PRZ{"Respondeu
no prazo?"}:::decisao TARDE["Pode ser perdida
mesmo com todas
as evidências"]:::erro MEIO{"Pix ou
cartão?"}:::decisao PIX["Finvia encaminha
as evidências a quem
analisa o MED"]:::finvia CART["Finvia apresenta
à adquirente, que
leva ao emissor"]:::finvia R1{"Devolução
aceita?"}:::decisao R2{"Disputa
ganha?"}:::decisao RFD["refunded
valor volta
ao pagador"]:::erro LIB["Bloqueio liberado
isBlocked: false, valor
volta ao disponível"]:::ok CB["chargeback
informado pela
adquirente"]:::erro E1[["charge.refunded"]]:::evento SEM["Nenhum webhook:
confirme com
GET /v1/charges/{id}"]:::neutro E2[["charge.updated
status chargeback
só na postbackUrl"]]:::evento E3[["charge.refunded
quando o valor é
revertido do saldo"]]:::evento MAIL --> EVI --> PRZ PRZ -->|"sim"| MEIO PRZ -->|"não"| TARDE MEIO -->|"Pix, MED"| PIX --> R1 MEIO -->|"cartão, chargeback"| CART --> R2 R1 -->|"sim"| RFD R1 -->|"não"| LIB R2 -->|"sim"| LIB R2 -->|"não"| CB RFD --> E1 LIB -.-> SEM CB --> E2 CB --> E3 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` O fluxo da defesa e o prazo para envio das evidências estão em validação (V-32 e V-53), como indicado no início da página. ## Desfechos | Desfecho | O que muda na cobrança | Aviso | | - | - | - | | Bloqueio liberado (disputa ganha ou MED recusado) | `isBlocked: false`, `blockedReason` apagado, `blockedAt` mantido. O valor volta ao saldo disponível | **Nenhum webhook**. Consulte a cobrança | | MED aceito (Pix) | Estorno: `status` `refunded` | `charge.refunded` | | Chargeback perdido (cartão) | `status` `chargeback`, informado pela adquirente | `charge.updated` com `status: "chargeback"` na `postbackUrl` e, quando o valor é revertido do saldo, `charge.refunded` (o `status` dentro desse payload pode vir `refunded` ou `chargeback`) | A passagem para `chargeback` acontece quando a adquirente informa a disputa à Finvia. Nem todas as adquirentes enviam esse aviso: confirme sempre o estado com `GET /v1/charges/{id}`. > [!TIP] > > **Para o desenvolvedor:** como a liberação não gera webhook, guarde as cobranças que você marcou como "em disputa" e consulte cada uma periodicamente com `GET /v1/charges/{id}`, ou compare com a lista de `GET /v1/charges?status=blocked`. Quando `isBlocked` voltar a `false` com `status` `paid`, restaure o pedido. ## Pré-chargeback O pré-chargeback é um alerta recebido pelos programas Ethoca e Verifi quando o titular contestou a compra no emissor, antes de o chargeback ser formalizado. O serviço é ativado conforme o seu contrato: * **Alerta com reembolso automático**, quando previsto em contrato: o valor é devolvido ao titular para que o alerta não evolua para chargeback formal. * O **custo do serviço de pré-alerta** (Ethoca/Verifi) é debitado da sua conta. Na API, a cobrança passa para `pre_chargeback` e os endpoints e a `postbackUrl` recebem `charge.pre_chargeback`. A `postbackUrl` recebe também o `charge.updated`. Se houve reembolso, sai ainda `charge.refunded`, com `chargeback_alert_refunded: true` no payload. | Campo (consulta e listagem) | Tipo | Significado | | - | - | - | | `chargebackAlertRefunded` | boolean ou `null` | `true`: o valor **já foi estornado** ao titular. `false`: alerta registrado **sem** estorno. `null` quando não há alerta | | `chargebackAlertReason` | string ou `null` | Motivo ou referência informado no alerta (ex.: `"Chargeback - NSU 123456789"`) | | `chargebackAlertRefunded` | Como marcar o pedido | | - | - | | `true` | Estornado (o valor já voltou ao titular) | | `false` | Em disputa, sem estorno | Uma cobrança já estornada no pré-chargeback não pode receber outro estorno. Se depois o chargeback for formalizado, só a `postbackUrl` recebe o `charge.updated` com `status: "chargeback"`. O desenho abaixo mostra o caminho de um alerta de pré-chargeback e como marcar o pedido em cada caso. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB TIT(["Titular contesta a compra
no banco emissor"]):::comprador ALR["Alerta Ethoca ou Verifi
antes do chargeback formal"]:::externo PRE["pre_chargeback
alerta de pré-chargeback"]:::alerta CUS["Custo do serviço
Ethoca/Verifi debitado
da sua conta"]:::alerta EV[["charge.pre_chargeback
endpoints e postbackUrl
+ charge.updated na postbackUrl"]]:::evento Q{"chargebackAlert
Refunded?"}:::decisao DEV["Valor devolvido ao titular
reembolso automático
previsto em contrato"]:::neutro RF[["charge.refunded com
chargeback_alert_
refunded: true"]]:::evento PED1(["Marque o pedido
como estornado"]):::lojista PED2(["Marque o pedido como
em disputa, sem estorno"]):::lojista FORM["Se o chargeback for
formalizado: charge.updated
status chargeback na postbackUrl"]:::erro TIT --> ALR --> PRE PRE --> EV PRE --> CUS PRE --> Q Q -->|"true"| DEV --> RF --> PED1 Q -->|"false"| PED2 PED1 -.-> FORM PED2 -.-> FORM classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ## Exemplos de payload > [tab] charge.blocked > > Envelope padrão, com as chaves de `data` em snake\_case. O exemplo mostra parte do objeto `data`. > > ```json theme={null} > { > "id": "2xKs9To6VbY1dP5rN0eX3fA8jLg", > "event": "charge.blocked", > "livemode": true, > "data": { > "id": "2vorkPx3Bl4Oc5Ke6Dd7Ab8CdEf", > "status": "paid", > "amount": 100, > "currency": "BRL", > "net": 99, > "merchant_id": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH", > "payment_method": { "type": "pix" }, > "is_blocked": true, > "blocked_at": "2026-10-20T09:00:00.000Z", > "blocked_reason": "MED em análise", > "metadata": { "orderId": "ORD-456" }, > "paid_at": "2026-10-15T14:31:00.000Z", > "is_test": false > } > } > ``` > [tab] charge.updated (bloqueio) > > Postback legado, só na `postbackUrl`: camelCase em todos os níveis, inclusive em `metadata`, sem `id` e sem `livemode`. O exemplo mostra parte do objeto `data`. > > ```json theme={null} > { > "event": "charge.updated", > "data": { > "id": "2vorkDcXyvzifL63YX09S9VqcnI", > "status": "paid", > "pspRefId": "card_ref_abc123", > "amount": 100, > "currency": "BRL", > "isBlocked": true, > "blockedAt": "2026-10-20T09:00:00.000Z", > "blockedReason": "Chargeback em análise", > "paymentMethod": { > "type": "credit_card", > "installments": 1, > "firstSix": "411111", > "lastFour": "1111", > "holderName": "JOAO DA SILVA" > }, > "merchantId": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH", > "metadata": { "orderId": "ORD-123" }, > "postbackUrl": "https://meusite.com.br/webhooks/finvia", > "isTest": false, > "updatedAt": "2026-10-20T09:00:00.000Z" > } > } > ``` > [tab] charge.pre\_chargeback > > Envelope padrão. O exemplo mostra parte do objeto `data`. > > ```json theme={null} > { > "id": "2xKt0Up7WcZ2eQ6sO1fY4gB9kMh", > "event": "charge.pre_chargeback", > "livemode": true, > "data": { > "id": "2vorkDcXyvzifL63YX09S9VqcnI", > "status": "pre_chargeback", > "amount": 100, > "currency": "BRL", > "chargeback_alert_refunded": true, > "chargeback_alert_reason": "Chargeback - NSU 123456789", > "merchant_id": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH", > "is_test": false > } > } > ``` ## Regras de negócio | Regra | Detalhe | | - | - | | Quem bloqueia | A equipe Finvia, só em cobrança `paid` | | Status durante o bloqueio | Continua `paid`. Use `isBlocked` | | Saldo | O valor já liquidado da venda vai para o saldo bloqueado; parcelas que liquidarem durante o bloqueio também | | Alerta | Por e-mail à conta (no Connect, à conta master), com os detalhes e o prazo | | Defesa | Em resposta ao e-mail do alerta, dentro do prazo. Não existe envio de defesa pela API | | Defesa fora do prazo | Pode ser perdida mesmo com todas as evidências | | Resultado | No cartão, depende do emissor e segue o fluxo das bandeiras. No Pix, segue as regras do MED | | Liberação | Sem webhook. Acompanhe pela consulta | | Pré-chargeback | Alerta mais reembolso automático quando previsto em contrato. O custo do serviço (Ethoca/Verifi) é debitado da conta | | Estorno | O lojista pede estorno só pela API (`POST /v1/refunds`). A Finvia não faz estorno por chamado, exceto em erro sistêmico. A devolução de um MED aceito e os débitos de chargeback são feitos pela Finvia | > [!WARNING] > > Uma cobrança em disputa ainda pode terminar com o valor devolvido ao cliente. Se o pedido é de produto físico ainda não enviado, avalie com a sua operação se o envio deve esperar o resultado. ## Implementação recomendada O desenho abaixo resume a lógica do código: o que fazer com cada aviso e a rotina que detecta a liberação do bloqueio. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB REQ(["POST no seu endpoint"]):::neutro R200["Responda 200 primeiro"]:::lojista ID{"O corpo tem id
de evento?"}:::decisao EVT{"Qual evento?"}:::decisao BLK["Pedido em disputa"]:::alerta AR{"chargeback_alert_
refunded?"}:::decisao EST["Pedido estornado"]:::neutro DIS["Pedido em disputa"]:::alerta REG["Registre o estorno
MED aceito ou chargeback
revertido do saldo"]:::neutro GET1["Legado charge.updated:
GET /v1/charges/{id}"]:::lojista CBQ{"status
chargeback?"}:::decisao PERDA["Registre a perda"]:::erro ROT(["Rotina periódica"]):::neutro GET2["GET /v1/charges/{id}
de cada pedido em disputa"]:::lojista LIBQ{"paid e
isBlocked false?"}:::decisao REST(["Restaure o pedido"]):::ok REQ --> R200 --> ID ID -->|"sim"| EVT ID -->|"não"| GET1 EVT -->|"charge.blocked"| BLK EVT -->|"charge.pre_chargeback"| AR EVT -->|"charge.refunded"| REG AR -->|"true"| EST AR -->|"false"| DIS GET1 --> CBQ CBQ -->|"sim"| PERDA ROT --> GET2 --> LIBQ LIBQ -->|"sim"| REST classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ```javascript Node.js theme={null} app.post('/webhooks/finvia', async (req, res) => { const { id, event, data } = req.body; res.status(200).send('OK'); // Envelope padrão (endpoints e postbackUrl): snake_case, com id de evento if (id) { if (event === 'charge.blocked') { await marcarPedido(data.id, 'em_disputa', data.blocked_reason); } if (event === 'charge.pre_chargeback') { const estado = data.chargeback_alert_refunded ? 'estornado' : 'em_disputa'; await marcarPedido(data.id, estado, data.chargeback_alert_reason); } if (event === 'charge.refunded') { await registrarEstorno(data.id); // inclui MED aceito e chargeback revertido do saldo } return; } // Postback legado (só postbackUrl): camelCase, sem id. Confirme na API antes de agir. if (event === 'charge.updated') { const charge = await consultarCobranca(data.id); // GET /v1/charges/{id} if (charge?.status === 'chargeback') { await registrarPerda(charge.id); } } }); // Rotina periódica: a liberação do bloqueio não gera webhook async function verificarDisputas() { for (const chargeId of await pedidosEmDisputa()) { const charge = await consultarCobranca(chargeId); if (charge?.status === 'paid' && charge.isBlocked === false) { await restaurarPedido(chargeId); } } } ``` > [!NOTE] > > O `charge.updated` chega só à `postbackUrl`, em camelCase e sem `id`/`livemode`. Os demais eventos seguem o envelope padrão, em snake\_case, e chegam aos endpoints e à `postbackUrl`. Se a mesma URL está cadastrada nos dois canais, ela recebe cada evento duas vezes: deduplique pelo `id` do evento. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Disputa perdida por prazo | A defesa foi enviada depois do prazo indicado no e-mail | Monitore o e-mail da conta (no Connect, da master) e responda dentro do prazo | | Ninguém viu o alerta | O e-mail da conta não é acompanhado pela equipe responsável | Garanta que o e-mail cadastrado chega a quem cuida das disputas | | Pedido fica "em disputa" para sempre | A liberação do bloqueio não gera webhook | Consulte a cobrança periodicamente e leia `isBlocked` | | Pedido tratado como liberado durante o bloqueio | O código olhou só `status` (`paid`) | Leia também `isBlocked` | | Pedido tratado como bloqueado depois da liberação | O código usou `blockedAt` | Use `isBlocked`: `blockedAt` continua preenchido | | Chargeback formalizado não chegou ao sistema | Cobrança criada sem `postbackUrl` | Informe `postbackUrl` em todas as cobranças de cartão | | Pedido marcado como estornado sem devolução | Pré-chargeback tratado sem ler `chargebackAlertRefunded` | Só marque como estornado quando `chargebackAlertRefunded` for `true` | ## Perguntas frequentes > [accordion] Como envio a defesa? > > Respondendo ao e-mail do alerta de chargeback ou MED, com as evidências, dentro do prazo indicado. Não existe envio de defesa pela API. > [accordion] MED e bloqueio cautelar são a mesma coisa? > > Não. O MED é o pedido de devolução de um Pix feito pela instituição do pagador. O bloqueio cautelar é uma retenção preventiva e curta, feita pela instituição do recebedor quando suspeita de fraude. Na API, os dois aparecem como bloqueio da cobrança (`isBlocked`). > [accordion] Existe MED no cartão? > > Não. O MED existe só no Pix. No cartão, o equivalente é o chargeback. > [accordion] Por que o status continua paid durante o bloqueio? > > Porque o pagamento aconteceu. O bloqueio só retém o valor enquanto o caso é analisado. Para saber se a cobrança está bloqueada, leia `isBlocked`. > [accordion] Qual a diferença entre pré-chargeback e chargeback? > > O pré-chargeback é um alerta recebido antes de o chargeback ser formalizado, e pode vir com o valor já devolvido ao titular. O chargeback é a disputa formal aberta pelo emissor. > [accordion] Posso filtrar as cobranças em disputa? > > Sim. `GET /v1/charges` aceita `status=blocked`, `status=pre_chargeback` e `status=chargeback`. ## Como testar O reenvio de webhook de teste ([`POST /v1/charges/{id}/resend-webhook`](/referencia/cobrancas/reenviar-webhook-teste)) não aceita `pre_chargeback` nem `chargeback` e não simula o bloqueio. Para testar o seu handler, envie ao seu próprio endpoint os payloads de exemplo desta página. Garanta também que o seu endpoint responde 2xx (cenários **CHG-08** e **CHG-09** do [roteiro de homologação](/homologacao/roteiro)). ## Veja também > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Formato do `charge.updated` e dos demais eventos. > [card] [Estorno](/guias/estorno) > > Devolução por iniciativa do merchant. > [card] [Consultar cobrança](/referencia/cobrancas/consultar) > > Campos `isBlocked`, `blockedAt` e `blockedReason`. > [card] [Status de cobrança](/anexos/status-de-cobranca) > > Todos os status e transições. # Clientes Source: https://docs.fastpaybrasil.com/guias/clientes Cadastre os compradores uma vez e reutilize o cadastro em cobranças, cartões salvos e assinaturas. O cadastro de clientes guarda os dados de quem compra de você: nome, e-mail, documento e telefone. Com o cliente cadastrado, cobranças, cartões salvos e assinaturas passam a apontar para o mesmo registro, o que facilita localizar o histórico de um comprador e evita digitar os mesmos dados a cada venda. > [!NOTE] > > **Para o negócio:** um cadastro único por comprador é o que permite oferecer recompra com cartão salvo e assinaturas, e também facilita o atendimento: com o e-mail ou o CPF do cliente, o seu time encontra o cadastro. Para operações de venda avulsa, o cadastro prévio é opcional, porque a própria cobrança pode criar o cliente. ## Quando usar | Situação | Recomendação | | - | - | | Venda avulsa por Pix ou cartão, sem recompra | Envie os dados do cliente direto na cobrança. A API cria ou localiza o cliente junto com a cobrança | | Cliente que volta a comprar (área logada, app) | Cadastre o cliente uma vez, guarde o `id` e use `customer.id` nas próximas cobranças | | Salvar cartão para recompra com um clique | Cadastro prévio obrigatório: `POST /v1/cards` exige `customerId` | | Assinatura | Use um cliente cadastrado (`customerId`) ou envie o objeto `customer` na criação da assinatura | | Sincronizar com o seu CRM ou ERP | Cadastre pela API e guarde o `id` da Finvia junto do seu registro | ## Como funciona O desenho abaixo mostra como o cadastro do cliente se liga às cobranças, aos cartões salvos e às assinaturas. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB SEU["Seu sistema
guarda o id do cliente"]:::lojista VIS(["Comprador visitante
sem cadastro prévio"]):::comprador CLI["Cliente na Finvia
name, email, documento"]:::finvia CARD["Cartão salvo
POST /v1/cards
exige e-mail e CPF ou CNPJ"]:::lojista COB["Cobrança
POST /v1/charges"]:::lojista ASS["Assinatura
POST /v1/subscriptions"]:::lojista SEU -->|"1. POST /v1/customers"| CLI CLI -.->|"2. devolve o id"| SEU SEU -->|"customer.id"| COB SEU -->|"customerId"| CARD SEU -->|"customerId"| ASS CARD -->|"id do cartão vira
cardTokenId + CVV"| COB CARD -->|"cardTokenId"| ASS VIS -->|"objeto customer
na cobrança"| COB COB -.->|"cria ou localiza
o cliente"| CLI classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 ``` **1. Crie o cliente** `POST /v1/customers` com nome, e-mail e documento. A resposta traz o `id`. **2. Guarde o id** Grave o `id` no cadastro do comprador no seu sistema. **3. Use o id nas operações** Em cobranças, envie `customer.id`. Em cartões, `customerId`. Em assinaturas, `customerId`. **4. Mantenha o cadastro atualizado** Atualize nome, e-mail e telefone com `PUT /v1/customers/{id}` quando o comprador alterar os dados. ## Criar o cliente antes ou na cobrança Há dois caminhos, e eles podem conviver na mesma integração. | | Criar antes (`POST /v1/customers`) | Criar na cobrança (inline) | | - | - | - | | Como | Chamada própria, depois `customer.id` na cobrança | Objeto `customer` com `name` e `email` (ou `phone`) dentro de `POST /v1/charges` | | O que a API faz | Cria o cliente e devolve o `id` | Cria ou localiza o cliente junto com a cobrança | | Dados exigidos | `name`, `email`, `documentId`, `documentType` | `email` ou `phone` (quando não há `id`) | | Serve para cartão salvo | Sim | Só depois de obter o `id` do cliente | | Indicado para | Áreas logadas, recompra, assinaturas, integração com CRM | Checkout de visitante, venda única | > [!NOTE] > > Quando a cobrança recebe `customer.id`, os outros campos de `customer` ficam opcionais e o cadastro existente é usado como está. Os dados enviados junto não atualizam o cadastro. Para mudar nome, e-mail ou telefone, use `PUT /v1/customers/{id}`. ## Regras de negócio | Regra | Detalhe | | - | - | | Campos obrigatórios na criação | `name`, `email`, `documentId`, `documentType` | | Tipos de documento | Use `cpf` ou `cnpj` em `documentType` | | Documento imutável | `documentId` e `documentType` não podem ser alterados depois da criação | | Cartão salvo e assinatura | O cliente precisa de **e-mail** e de **CPF ou CNPJ**. O tipo é deduzido pela quantidade de dígitos do documento: 11 é CPF, 14 é CNPJ. Qualquer outro tamanho conta como cliente sem documento, e o cartão é recusado | | Exclusão | Lógica (soft delete): o cliente é removido do sistema e a rota responde `204` | | Listagens | Paginação por `page` e `size` (padrão 1 e 10). Um parâmetro `limit` é ignorado sem erro | | Nome do campo de telefone | `phoneNumber` no cadastro de clientes e nas assinaturas; `phone` dentro de `customer` na cobrança | > [!WARNING] > > Se o cliente vai ter cartão salvo ou assinatura, cadastre com CPF ou CNPJ e e-mail desde o início. Sem isso, o cadastro do cartão responde `400` com `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador`. Como o documento não pode ser alterado, um cliente criado com outro documento (passaporte, RG) não serve para esses fluxos, e será preciso criar outro cadastro. ## Passo a passo ### 1. Criar um cliente ```http REST (JSON) theme={null} POST /v1/customers HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/customers', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Joao Silva', email: 'joao@email.com', documentId: '52998224725', documentType: 'cpf', phoneNumber: '+5511987654321', }), }); const { id } = await response.json(); // guarde este id ``` ```python Python theme={null} import os import requests payload = { "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/customers", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'Joao Silva', 'email' => 'joao@email.com', 'documentId' => '52998224725', 'documentType' => 'cpf', 'phoneNumber' => '+5511987654321', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/customers'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/customers"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/customers", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/customers") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "name" => "Joao Silva", "email" => "joao@email.com", "documentId" => "52998224725", "documentType" => "cpf", "phoneNumber" => "+5511987654321", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201`: ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" } ``` | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `name` | string | Sim | Nome completo do cliente | | `email` | string (e-mail) | Sim | E-mail do cliente | | `documentId` | string | Sim | Número do documento: CPF (11 dígitos) ou CNPJ (14 dígitos) | | `documentType` | string | Sim | Tipo do documento: `cpf` ou `cnpj` | | `phoneNumber` | string | Não | Telefone do cliente. Ex.: `+5511987654321` | ### 2. Usar o cliente numa cobrança ```json theme={null} { "amount": 150, "currency": "BRL", "customer": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" }, "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, "items": [ { "title": "Consultoria online", "type": "digital", "description": "Sessão de 1 hora por vídeo", "unit_price": 150, "quantity": 1 } ] } ``` A alternativa sem cadastro prévio é enviar os dados no próprio `customer`: ```json theme={null} { "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" } } } ``` ### 3. Buscar e listar clientes `GET /v1/customers` devolve uma lista paginada, dos clientes mais recentes para os mais antigos, e aceita estes filtros: | Parâmetro | Tipo | Padrão | Descrição | | - | - | - | - | | `search` | string | | Busca por nome, e-mail, documento ou telefone | | `email` | string | | Filtra pelo e-mail exato | | `documentId` | string | | Filtra pelo número do documento | | `page` | integer | `1` | Número da página (começa em 1). Valor menor que 1 ou não numérico volta ao padrão | | `size` | integer | `10` | Itens por página. Valor menor que 1 ou não numérico volta ao padrão | ```bash Busca por texto theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10" \ -u "$FINVIA_API_KEY:" ``` ```bash Por e-mail exato theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/customers?email=joao@email.com" \ -u "$FINVIA_API_KEY:" ``` ```bash Por documento theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/customers?documentId=52998224725" \ -u "$FINVIA_API_KEY:" ``` A resposta `200` usa o envelope plano das listagens da API: `{ data, total, page, size, pages }`. Para percorrer todos os clientes, avance `page` até chegar a `pages`. Os campos de cada cliente em `data` serão publicados na [referência da rota](/referencia/clientes/listar) quando o time técnico liberar o formato final. > [!TIP] > > **Para o desenvolvedor:** o tamanho da página vai em `size`. Um `limit` na URL é ignorado sem erro, e a página continua com 10 itens. Para buscar um cliente específico, use `GET /v1/customers/{id}`: ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` A resposta `200` traz o cadastro do cliente. Os campos estão descritos em [Consultar cliente](/referencia/clientes/consultar). ### 4. Atualizar um cliente `PUT /v1/customers/{id}` altera nome, e-mail e telefone. Todos os campos são opcionais: envie só o que mudou. O documento (`documentId` e `documentType`) não pode ser alterado. ```bash cURL theme={null} curl -X PUT "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "email": "joao.silva@email.com", "phoneNumber": "+5511912345678" }' ``` A resposta `200` traz o cadastro do cliente, no mesmo formato da consulta. ### 5. Excluir um cliente ```bash cURL theme={null} curl -X DELETE "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` A exclusão é lógica (soft delete): o cliente é marcado como removido. A resposta é `204`, sem corpo. > [!NOTE] > > A documentação não detalha o efeito da exclusão do cliente sobre cartões salvos e assinaturas já existentes. Antes de excluir um cliente com assinatura ativa, cancele a assinatura e exclua os cartões pelas rotas próprias. ## Boas práticas para evitar duplicidade Clientes duplicados dificultam o atendimento e espalham o histórico de um comprador em vários registros. Algumas práticas ajudam: 1. **Guarde o `id` da Finvia** no cadastro do comprador no seu sistema e use sempre esse `id` quando ele existir. 2. **Procure antes de criar.** Se o seu sistema não tem o `id`, consulte `GET /v1/customers?email=...` ou `?documentId=...`. Crie só se a busca vier vazia. 3. **Padronize os dados.** Envie o documento só com números (`52998224725`) e o e-mail em minúsculas, para que as buscas exatas encontrem o registro. 4. **Use o objeto `customer` com cuidado.** Na cobrança e na assinatura, o objeto `customer` cria ou localiza o cliente (na assinatura, a busca é pelo e-mail). Se o mesmo comprador usar e-mails diferentes, podem surgir dois cadastros. Na assinatura, quando já existe um cliente com o mesmo e-mail, vale o documento desse cadastro, e não o enviado na requisição. O desenho abaixo resume essas práticas em uma sequência de decisões. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Comprador vai pagar"]):::comprador Q1{"Já tem o id
da Finvia?"}:::decisao USE(["Use o id: customer.id
na cobrança, customerId
no cartão e na assinatura"]):::ok BUS["Procure antes de criar
GET /v1/customers
?email= ou ?documentId="]:::lojista Q2{"Achou?"}:::decisao Q3{"Cartão salvo, assinatura
ou recompra?"}:::decisao CRIA["POST /v1/customers
com e-mail e CPF ou CNPJ
só com números"]:::lojista INL["Venda avulsa: envie
o objeto customer
direto na cobrança"]:::neutro GRD["Guarde o id junto do
cadastro no seu sistema"]:::lojista INI --> Q1 Q1 -->|"sim"| USE Q1 -->|"não"| BUS --> Q2 Q2 -->|"sim"| GRD Q2 -->|"não"| Q3 Q3 -->|"sim"| CRIA --> GRD Q3 -->|"não"| INL GRD --> USE classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` `Unauthorized` | Chave inválida ou cabeçalho mal montado | Confira a autenticação em [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) | | `403` `Acesso negado` ao criar | Chave sem permissão | Gere a chave com usuário Owner ou Manager | | `404` `Customer not found` | `id` inexistente ou cliente excluído | Confira o `id` ou busque por e-mail ou documento | | Documento não muda após o `PUT` | `documentId` e `documentType` são imutáveis | Crie um novo cadastro com o documento correto | | Cartão ou assinatura recusados com `O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 nem 14 dígitos | Use um cadastro com e-mail e CPF ou CNPJ | | Assinatura recusada mesmo com CPF na requisição | Já existe um cliente com o mesmo e-mail, cadastrado com outro documento. Vale o documento do cadastro | Crie um cliente com e-mail e CPF ou CNPJ e envie o `customerId` dele | | A página sempre volta com 10 clientes | Tamanho enviado como `limit` | Envie `size` | | Telefone não salvo | Campo enviado como `phone` no cadastro | No cadastro de clientes o campo é `phoneNumber` | ## Perguntas frequentes > [accordion] Preciso cadastrar o cliente antes de cobrar? > > Não. A cobrança aceita o objeto `customer` com `name` e `email` (ou `phone`) e cria ou localiza o cliente. O cadastro prévio é necessário para salvar cartão e recomendado para recompra e assinaturas. > [accordion] Posso corrigir um CPF digitado errado? > > Não. O documento não pode ser alterado depois da criação. Crie um novo cadastro com o documento correto e passe a usar o novo `id` (em assinaturas, envie `customerId`). Se você enviar o objeto `customer` com o mesmo e-mail do cadastro antigo, a assinatura usa o documento do cadastro antigo. > [accordion] Posso cadastrar cliente estrangeiro? > > Cartão salvo e assinaturas exigem CPF ou CNPJ: o tipo é deduzido pela quantidade de dígitos do documento, e um passaporte conta como cliente sem documento. Para vendas avulsas, a cobrança pode ser feita com os dados do cliente na própria requisição. > [accordion] A API impede a criação de dois clientes com o mesmo e-mail? > > A documentação não informa se há bloqueio de duplicidade em `POST /v1/customers`. Procure o cliente antes de criar, como mostrado em [Boas práticas](#boas-práticas-para-evitar-duplicidade). > [accordion] Excluir o cliente apaga as cobranças dele? > > A exclusão é lógica (soft delete). A documentação não descreve o efeito sobre as cobranças já feitas para esse cliente. ## Como testar O cadastro de clientes funciona com a chave de teste (`sk_test_`). Crie, atualize e exclua um cliente no sandbox antes de ir para produção. O cadastro de cartão e as assinaturas não têm modo de teste: veja [Cofre de cartões](/guias/cofre-de-cartoes). | Código | Cenário | Relação com clientes | | - | - | - | | SUB-01 | Registrar cartão | O cliente precisa ter e-mail e CPF ou CNPJ | | SUB-04 | Criar assinatura | Com `customerId` ou objeto `customer` | ## Veja também > [card] [Cofre de cartões](/guias/cofre-de-cartoes) > > Salve cartões vinculados ao cliente. > [card] [Assinaturas](/guias/assinaturas/visao-geral) > > Cobrança recorrente a partir do cliente cadastrado. > [card] [Criar cliente](/referencia/clientes/criar) > > Contrato completo da rota. > [card] [Listar clientes](/referencia/clientes/listar) > > Filtros e paginação. # Apple Pay Source: https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay Aceite Apple Pay no seu site sem conta Apple Developer: registre o domínio, valide a sessão no navegador e envie o token na cobrança. O Apple Pay permite que o cliente pague com um cartão que já está na Wallet do iPhone, do iPad ou do Mac, sem digitar número, validade ou CVV. Na Finvia, a integração é **pass-through**: o token cifrado gerado pelo dispositivo do cliente vem para a Finvia e é repassado ao processador, que mantém a relação com a Apple e faz a decifragem. Por isso, você **não precisa** de conta no Apple Developer Program, de Merchant ID nem de certificados. > [!NOTE] > > **Para o negócio:** o Apple Pay é uma forma de pagamento com cartão de crédito. A venda segue as regras do cartão (parcelamento, estorno, webhooks) e aparece como cobrança de cartão. Ela só aceita reais (`BRL`), exige o CPF ou CNPJ do cliente e, neste modelo, aceita Visa e Mastercard (Elo em homologação pelo processador). ## Quando usar | Situação | Recomendação | | - | - | | Checkout web com público que usa iPhone, iPad ou Mac | Ofereça o botão Apple Pay ao lado do cartão e do Pix | | Venda em reais para clientes no Brasil | Apple Pay atende | | Venda em outra moeda | Use cartão digitado. O Apple Pay pass-through só aceita `BRL` | | Cliente com Android | O botão não aparece. Ofereça cartão ou Pix | | A sua conta já operava Apple Pay com certificado próprio | Leia a seção "Migração", no fim desta página, antes de registrar qualquer domínio | ## Como funciona A integração tem três partes: preparar o domínio (feito uma vez), validar a sessão a cada compra e criar a cobrança. O primeiro desenho mostra a preparação do domínio, feita uma vez por hostname: registrar, hospedar o arquivo e validar. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(243,245,248) Sua aplicação participant L as Seu backend (sk_) participant D as Seu site (o domínio) end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant P as Processador end L->>F: POST /v1/apple-pay/domains · domain (só o hostname) F->>P: Registra o domínio F-->>L: 201 · id · status pending · verificationFile Note over L,P: O primeiro domínio registrado já liga o modelo pass-through na conta L->>D: Publica verificationFile.content no caminho /.well-known/ indicado L->>F: POST /v1/apple-pay/domains/{id}/validate F->>P: Pede a conferência do arquivo P->>D: Lê o arquivo (HTTPS, 200, text/plain, sem redirect) alt Arquivo correto F-->>L: 200 · status verified · verifiedAt preenchido else Arquivo ausente, alterado ou com redirect F-->>L: 422 · APPLE_PAY_DOMAIN_VERIFICATION_FAILED · status failed Note over L,D: Corrija a hospedagem e chame a validação de novo end ``` O mesmo hostname registrado vale para produção e para o Modo Teste. `www.loja.com` e `loja.com` são registros diferentes. O segundo desenho mostra o que acontece a cada compra, do toque no botão até a resposta da cobrança. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant N as Navegador com Apple Pay JS participant L as Seu backend end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant P as Processador e Apple end Note over C,N: CPF ou CNPJ já coletado no checkout C->>N: Toca no botão Apple Pay N->>N: onvalidatemerchant · validationURL N->>F: POST /v1/apple-pay/validate-merchant · pk_ · validationUrl + domain F->>P: Valida a sessão no provedor F-->>N: 200 · sessão da Apple, opaca N->>P: completeMerchantValidation · sessão como veio · a folha abre C->>P: Autoriza com Face ID, Touch ID ou no iPhone P-->>N: onpaymentauthorized · payment.token N->>L: Envia o payment.token inteiro, sem alterar L->>F: POST /v1/charges · sk_ · wallet + customer.document F->>P: Repassa o token cifrado, sem decifrar F-->>L: 201 · paid ou refused L-->>N: Resultado da cobrança N-->>C: completePayment · sucesso ou falha ``` Só a validação da sessão sai do navegador, com a chave pública. A cobrança é sempre criada pelo seu backend, com a chave secreta. **1. Registre o domínio (backend, chave secreta)** Seu backend chama `POST /v1/apple-pay/domains` com o hostname onde o botão aparece. A Finvia registra o domínio no processador e devolve o arquivo de verificação (`verificationFile`). **2. Hospede o arquivo de verificação** Você publica o conteúdo do arquivo em `/.well-known/apple-developer-merchantid-domain-association` no seu domínio. **3. Valide o domínio (backend, chave secreta)** Seu backend chama `POST /v1/apple-pay/domains/{id}/validate`. O processador confere o arquivo e o domínio passa a `verified`. **4. Valide a sessão a cada compra (navegador, chave pública)** Quando o cliente toca no botão, o Apple Pay JS dispara `onvalidatemerchant`. O navegador chama `POST /v1/apple-pay/validate-merchant` com a chave pública e devolve à Apple a sessão recebida, sem alterar. **5. O cliente autoriza o pagamento** O cliente confirma com Face ID, Touch ID ou no iPhone. O Apple Pay JS entrega o `payment.token` no evento `onpaymentauthorized`. **6. Crie a cobrança (backend, chave secreta)** O navegador envia o token ao seu backend, que chama `POST /v1/charges` com o token em `paymentMethod.wallet`. A Finvia repassa o token ao processador e devolve `paid` ou `refused`. As rotas estão na Referência: [registrar](/referencia/apple-pay/registrar-dominio), [listar](/referencia/apple-pay/listar-dominios), [consultar](/referencia/apple-pay/consultar-dominio) e [validar](/referencia/apple-pay/validar-dominio) domínio, e [validar sessão](/referencia/apple-pay/validar-sessao). > [!NOTE] > > **Para o negócio:** registrar o primeiro domínio é o passo que liga o Apple Pay na sua integração. A partir dele, a conta passa a usar o modelo em que a sessão é validada pela Finvia (`validate-merchant`). ## Pré-requisitos | Item | Detalhe | | - | - | | Chave secreta (`sk_`) | Para registrar e validar domínios e para criar a cobrança, no backend. Para os domínios, o usuário dono da chave precisa da permissão de domínios Apple Pay (perfis Owner, Manager e Desenvolvedor); sem ela, `403` `Acesso negado`. Para criar a cobrança, a chave precisa ser de um usuário Owner ou Manager | | Chave pública (`pk_`) | Para validar a sessão a partir do navegador. A conta precisa estar ativa. A chave precisa estar vinculada a **um único merchant**: uma chave compartilhada por vários merchants torna a checagem do domínio ambígua | | Domínio próprio em HTTPS | Certificado válido e sem redirecionamento no caminho `/.well-known/` | | Apple Pay JS SDK | Versão 1.2.0 ou superior, com o elemento `` registrado pelo SDK ([documentação da Apple](https://developer.apple.com/documentation/apple_pay_on_the_web)) | | CPF ou CNPJ do cliente | Coletado no seu checkout **antes** de abrir a folha de pagamento do Apple Pay | > [!NOTE] > > É o SDK da Apple que leva o Apple Pay para fora do Safari. Um botão feito só com CSS funciona apenas no WebKit (Safari e navegadores do iOS). ### Onde o botão aparece | Dispositivo do cliente | Navegador | Experiência | | - | - | - | | iPhone ou iPad | Safari, Chrome, Edge, Firefox e outros | Folha nativa do Apple Pay no próprio dispositivo (no iOS todos os navegadores usam o WebKit) | | Mac | Safari | Folha nativa do Apple Pay, com Touch ID ou confirmação no iPhone ou Apple Watch | | Mac ou PC com Windows | Chrome, Edge, Firefox e outros | O SDK abre um modal com um código. O cliente escaneia com a câmera do iPhone (iOS 18 ou superior) e autoriza no iPhone | | Android | Qualquer | Sem Apple Pay: `canMakePayments()` retorna `false` e o botão não aparece | A integração é a mesma em todos esses casos: o `onvalidatemerchant` chama a mesma rota da Finvia e o token autorizado chega no mesmo formato. A única exigência é avaliar `canMakePayments()` **depois** do evento `load` do SDK, porque fora do Safari é o SDK que define `ApplePaySession`. > [!NOTE] > > Cada hostname é um registro próprio: `www.loja.com` e `loja.com` são domínios diferentes. Registre exatamente o hostname que o navegador mostra em `window.location.hostname`. ## Regras de negócio | Regra | Detalhe | | - | - | | Moeda | Somente `BRL`. Outra moeda é recusada com `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | | Documento do cliente | `customer.document` obrigatório. O token da Apple não traz CPF/CNPJ (`APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED`) | | Versão do token | Só `EC_v1` | | Token | Enviado na íntegra, sem alterar nenhum campo (`APPLE_PAY_TOKEN_INVALID` se vier fora do formato) | | Parcelas | `installments` continua obrigatório, de `1` a `12` | | Campos de cartão | Com `wallet`, `number`, `holderName`, `expirationMonth`, `expirationYear` e `cvv` não são exigidos | | 3D Secure | Não se aplica: a autenticação já vem no token | | Domínio | Precisa estar `verified` e pertencer ao merchant da chave pública. Um domínio registrado vale para produção e para o Modo Teste | | Quem cria a cobrança | Sempre o backend, com a chave secreta. A chave pública só valida a sessão | > [!WARNING] > > O registro do **primeiro domínio** muda o modelo de Apple Pay da sua conta para pass-through **no mesmo instante**. Se você já operava com certificado próprio, siga a ordem da seção "Migração", no fim desta página, antes de registrar. ## Passo a passo ### Etapa 1: registrar o domínio Chame a rota com a chave secreta. A resposta traz o arquivo de verificação que você vai hospedar. ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/apple-pay/domains" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "domain": "checkout.minhaloja.com.br" }' ``` Resposta `201 Created`: ```json theme={null} { "id": "2xYq8Lm3NcR7tVb1KdZ4wP6sQhE", "domain": "checkout.minhaloja.com.br", "status": "pending", "verifiedAt": null, "lastVerificationError": null, "verificationFile": { "path": "https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association", "content": "7B227073706964223A22..." }, "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:00:00.000Z" } ``` | Campo | Descrição | | - | - | | `id` | Identificador do registro. Use na validação (Etapa 3) | | `status` | `pending` (aguardando verificação), `verified` (pronto para uso) ou `failed` (a última tentativa falhou; veja `lastVerificationError`) | | `verificationFile.path` | Localização do arquivo informada pelo processador, quando disponível. O caminho que precisa responder é sempre o da Etapa 2 | | `verificationFile.content` | Conteúdo do arquivo, a ser servido **como está**, sem decodificar | > [!TIP] > > **Para o desenvolvedor:** o `domain` é só o hostname, com até 255 caracteres. Sem `https://`, sem porta, sem caminho e sem IP. Se vier com algum desses, a API responde `400` com `APPLE_PAY_INVALID_DOMAIN`. O valor é gravado em minúsculas. Envie só o campo `domain` no corpo. **Registrar de novo é seguro.** Registrar o mesmo hostname na mesma conta é idempotente: a API devolve o registro que já existe, também com `201`, sem criar outro. Isso vale também quando a tentativa anterior falhou: o registro preservado no processador é reaproveitado. Se `verificationFile.content` vier `null`, o registro existe mas não há arquivo para hospedar. Nesse caso, não repita a chamada: fale com o suporte. #### Domínio compartilhado por vários merchants Plataformas de checkout que servem várias lojas em um mesmo hostname (por exemplo, `checkout.plataforma.com`) registram esse hostname uma vez **para cada merchant**, com a `sk_` de cada um. * Cada registro é independente: tem o próprio `id`, o próprio `status` e habilita o pass-through daquele merchant. * O arquivo de verificação é o mesmo para todos os registros da conta, então basta hospedá-lo uma vez por hostname. Os registros seguintes já nascem com o `status` que o hostname tem. * Lojas com domínio próprio registram também o domínio próprio. O navegador sempre envia o hostname real da página no validate-merchant. ### Etapa 2: hospedar o arquivo de verificação Sirva o valor de `verificationFile.content` neste endereço: ```text theme={null} https:///.well-known/apple-developer-merchantid-domain-association ``` Requisitos: * Caminho **sem extensão** (não é `.txt`). * `Content-Type: text/plain`. * HTTPS válido, resposta `200`, **sem redirect** (nem HTTP para HTTPS, nem para `www`). * Acesso público, sem autenticação. Confira antes de validar: ```bash theme={null} curl -sI https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association # HTTP/2 200 # content-type: text/plain ``` > [tab] Node.js (Express) > > ```javascript theme={null} > // Conteúdo recebido em verificationFile.content, guardado em variável de ambiente > const APPLE_PAY_FILE = process.env.APPLE_PAY_VERIFICATION_CONTENT; > > app.get('/.well-known/apple-developer-merchantid-domain-association', (req, res) => { > res.type('text/plain').status(200).send(APPLE_PAY_FILE); > }); > ``` > [tab] Nginx > > ```nginx theme={null} > location = /.well-known/apple-developer-merchantid-domain-association { > default_type text/plain; > alias /var/www/apple-pay/apple-developer-merchantid-domain-association; > } > ``` ### Etapa 3: validar o domínio ```bash theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate" \ -u "$FINVIA_API_KEY:" ``` A resposta é o mesmo objeto da Etapa 1, com `status: "verified"` e `verifiedAt` preenchido. Se o arquivo não estiver acessível, a API responde `422` com o código `APPLE_PAY_DOMAIN_VERIFICATION_FAILED`. O domínio passa a `status: "failed"` e o motivo fica em `lastVerificationError`. Corrija a hospedagem e chame de novo. Para consultar a qualquer momento: | Rota | Retorno | | - | - | | [`GET /v1/apple-pay/domains`](/referencia/apple-pay/listar-dominios) | `{ "data": [...] }` com todos os domínios da conta, do mais recente para o mais antigo, sem paginação | | [`GET /v1/apple-pay/domains/{id}`](/referencia/apple-pay/consultar-dominio) | Um domínio, com o arquivo de verificação | > [!TIP] > > O domínio está pronto quando `GET /v1/apple-pay/domains` mostra `status: "verified"` para o hostname exato da página do checkout. ### Etapa 4: validar a sessão no navegador No evento `onvalidatemerchant`, envie à Finvia a `validationURL` recebida da Apple e o hostname da página, autenticando com a **chave pública**. Devolva a sessão à Apple **sem modificar**. ```javascript theme={null} const session = new ApplePaySession(3, { countryCode: 'BR', currencyCode: 'BRL', supportedNetworks: ['visa', 'masterCard'], merchantCapabilities: ['supports3DS'], total: { label: 'Minha Loja', amount: '100.50' }, }); session.onvalidatemerchant = async (event) => { try { const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/apple-pay/validate-merchant', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Basic ' + btoa('pk_SUA_CHAVE_PUBLICA:'), }, body: JSON.stringify({ validationUrl: event.validationURL, domain: window.location.hostname, }), }, ); if (!response.ok) throw new Error('validate-merchant failed'); session.completeMerchantValidation(await response.json()); } catch (error) { session.abort(); } }; session.onpaymentauthorized = async (event) => { // Enviar event.payment.token ao seu backend, que cria a cobrança (Etapa 5) const result = await createChargeOnYourBackend(event.payment.token); session.completePayment( result.status === 'paid' ? ApplePaySession.STATUS_SUCCESS : ApplePaySession.STATUS_FAILURE, ); }; // Chame begin() de forma síncrona dentro do handler de clique do botão. session.begin(); ``` > [!NOTE] > > Regras do Safari: avalie `ApplePaySession.canMakePayments()` depois do evento `load` do SDK, registre o clique diretamente no elemento `` e chame `session.begin()` sem nenhum `await` antes. > [!NOTE] > > **Modo Teste:** uma chave `pk_test_` valida a sessão no provedor real (a folha do Safari só abre com sessão real), mas a cobrança correspondente cai no processador de teste e nenhum valor é movimentado. O limite de validações é de 20 tentativas por IP a cada 5 minutos, além de um teto global da plataforma. > [!TIP] > > **Para o desenvolvedor:** a chave pública pode ficar no código do navegador, porque ela só é aceita nas rotas que pedem por ela. A chave secreta nunca vai para o front-end. O `label` mostrado na folha do Apple Pay vem de `total.label`. ### Etapa 5: criar a cobrança Envie o objeto `payment.token` **na íntegra** em `paymentMethod.wallet`, pela rota padrão [`POST /v1/charges`](/referencia/cobrancas/criar). A cobrança é criada pelo seu backend, com a chave secreta. Com `wallet` presente, os campos do cartão (`number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`) não são necessários; `installments` continua obrigatório. ```json theme={null} { "amount": 100.5, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "phone": "+5511987654321", "document": { "type": "cpf", "id": "52998224725" }, "address": { "country": "BRA" } }, "paymentMethod": { "type": "credit_card", "installments": 1, "wallet": { "type": "applepay", "token": { "paymentData": { "version": "EC_v1", "data": "", "signature": "", "header": { "ephemeralPublicKey": "", "publicKeyHash": "", "transactionId": "" } }, "paymentMethod": { "displayName": "Visa 1234", "network": "Visa", "type": "credit" }, "transactionIdentifier": "" } } }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100.5, "quantity": 1 } ] } ``` Exemplo do lado do backend, recebendo o token do navegador: ```javascript Node.js theme={null} app.post('/checkout/apple-pay', async (req, res) => { const { token, pedidoId } = req.body; // token = event.payment.token, sem alterações const pedido = await buscarPedido(pedidoId); const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', { method: 'POST', headers: { Authorization: `Basic ${Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64')}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: pedido.total, currency: 'BRL', customer: { name: pedido.nome, email: pedido.email, document: { type: 'cpf', id: pedido.cpf }, // coletado antes de abrir o Apple Pay }, paymentMethod: { type: 'credit_card', installments: 1, wallet: { type: 'applepay', token }, }, items: pedido.itens, }), }); const charge = await response.json(); res.json({ status: charge.status, chargeId: charge.id }); }); ``` A Finvia não decifra o conteúdo de `paymentData`: ele é repassado ao processador exatamente como veio. Só a versão `EC_v1` do token é aceita, e o pass-through opera apenas em **BRL**. O 3D Secure não se aplica ao Apple Pay, porque a autenticação já está embutida no token. A resposta tem o mesmo formato de qualquer cobrança com cartão (`id`, `status`, `paymentDetails`, `reason`), e o pós-venda (webhooks, estorno, chargeback) segue as regras do [cartão de crédito](/guias/cobrancas/cartao-de-credito). ## Redes suportadas | Rede | Situação | | - | - | | Visa | Suportada | | Mastercard | Suportada | | Elo | Em homologação pelo processador | Configure `supportedNetworks` no `ApplePaySession` apenas com as redes suportadas (`['visa', 'masterCard']`), para o cliente não autorizar um pagamento que será recusado. ## Códigos de erro | Código | HTTP | Quando | | - | - | - | | `APPLE_PAY_INVALID_DOMAIN` | 400 | `domain` não é um hostname puro (tem esquema, porta, caminho, é um IP ou é inválido) | | `APPLE_PAY_DOMAIN_ALREADY_REGISTERED` | 409 | Duas chamadas simultâneas registrando o mesmo hostname para o mesmo dono. Repita a chamada: o registro que venceu a corrida é devolvido | | `APPLE_PAY_DOMAIN_NOT_FOUND` | 404 | `id` inexistente ou de outra conta | | `APPLE_PAY_DOMAIN_VERIFICATION_FAILED` | 422 | Arquivo de verificação ausente ou inacessível | | `APPLE_PAY_DOMAIN_NOT_VERIFIED` | 400 | `validate-merchant` para domínio que não é seu, não registrado ou ainda não verificado | | `APPLE_PAY_INVALID_VALIDATION_URL` | 400 | `validationUrl` não é uma URL HTTPS em `apple.com` ou subdomínio, sem porta e com até 2048 caracteres | | `APPLE_PAY_PROVIDER_NOT_ENABLED` | 422 | A conta ainda não está no modelo pass-through: registre o domínio (Etapa 1) para habilitá-lo | | `APPLE_PAY_RATE_LIMITED` | 429 | Mais de 20 validações de sessão do mesmo IP em 5 minutos, ou teto global da plataforma atingido. Aguarde alguns minutos | | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | 422 | O processador de Apple Pay não está configurado para a sua conta. Fale com o suporte | | `APPLE_PAY_TOKEN_INVALID` | 400 | O objeto enviado em `wallet.token` não está no formato do token da Apple. Envie-o na íntegra, sem reescrever campos | | `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` | 400 | `customer.document` ausente. O token da Apple não traz CPF/CNPJ e o processador exige o documento em toda cobrança: colete-o no seu checkout antes de abrir a folha de pagamento | | `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | 422 | Cobrança com Apple Pay pass-through em moeda diferente de `BRL` | | `APPLE_PAY_PROVIDER_REJECTED` | 400 | O processador recusou a operação ou devolveu uma resposta fora do contrato | | `APPLE_PAY_PROVIDER_UNAVAILABLE` | 503 | Processador indisponível ou limite de requisições atingido no processador. Tente de novo | | `APPLE_PAY_PROVIDER_AUTH_FAILED` | 500 | Falha de autenticação entre a Finvia e o processador. Fale com o suporte | ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `validate-merchant` responde `400` `APPLE_PAY_DOMAIN_NOT_VERIFIED` | O `domain` enviado é diferente do registrado, é de outro merchant ou ainda não está `verified` | Confira com `GET /v1/apple-pay/domains` e valide o domínio (Etapa 3) | | `validate-merchant` responde `422` `APPLE_PAY_PROVIDER_NOT_ENABLED` | A conta ainda não está no modelo pass-through | Registre o primeiro domínio (Etapa 1): é o registro que habilita o fluxo | | `validate-merchant` responde `429` `APPLE_PAY_RATE_LIMITED` | Mais de 20 validações do mesmo IP em 5 minutos | Não repita a chamada em laço: valide a sessão uma vez por clique no botão | | `403` `Acesso negado` ao registrar ou validar domínio | Usuário dono da chave sem permissão de domínios Apple Pay | Gere a chave com um usuário Owner, Manager ou Desenvolvedor | | Validação do domínio falha com `422` | Arquivo inacessível ou servido de forma errada | Rode o `curl -sI` da Etapa 2: caminho sem extensão, `text/plain`, sem redirect e conteúdo sem alterações | | O botão não aparece | Android, SDK não carregado, `canMakePayments()` avaliado cedo demais ou cliente sem cartão na Wallet | Confira a tabela "Onde o botão aparece". Em Chrome, Edge ou Firefox no Mac e no Windows, o botão só existe com o SDK e o elemento `` | | Cobrança recusada com `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` | CPF/CNPJ não enviado | Colete o documento antes de abrir o Apple Pay e envie em `customer.document` | | Cobrança recusada com `APPLE_PAY_TOKEN_INVALID` | Token alterado ou reescrito no caminho | Envie `event.payment.token` exatamente como veio | ## Perguntas frequentes > [accordion] Preciso de conta Apple Developer ou de certificado? > > Não. No modelo pass-through, a relação com a Apple é do processador. Você só registra e verifica o domínio pela API da Finvia. > [accordion] Posso usar a chave pública no código do site? > > Sim. A chave pública (`pk_`) foi feita para o navegador e é usada só no `validate-merchant`. A cobrança é criada pelo seu backend com a chave secreta, que nunca vai para o front-end. > [accordion] Tenho [www.minhaloja.com.br](http://www.minhaloja.com.br) e minhaloja.com.br. Registro os dois? > > Sim, se o botão aparecer nos dois. Cada hostname é um registro próprio e precisa ser verificado. > [accordion] Apple Pay aceita parcelamento? > > O campo `installments` é obrigatório na cobrança com Apple Pay, com a mesma regra do cartão digitado: um inteiro de 1 a 12. > [accordion] Como testo o Apple Pay? > > Com a chave `pk_test_`, a sessão é validada no provedor real (o botão precisa abrir no Safari) e a cobrança feita com a `sk_test_` cai no processador de teste, sem movimentar valor. No sandbox, a cobrança Apple Pay não tem um número de cartão controlável e, na prática, sai aprovada: não há como forçar uma recusa com o token da Apple. Para testar o tratamento de recusa, use uma cobrança de cartão digitado com o cartão `4444333322221112`. ## Como testar Execute a seção "Apple Pay" do [roteiro de homologação](/homologacao/roteiro): * **AP-01:** obter o token de pagamento no front (Apple Pay JS). * **AP-02:** cobrança Apple Pay aprovada, com `paid`. * **AP-03:** domínio registrado e verificado (`GET /v1/apple-pay/domains` com `status: "verified"`) e sessão validada pelo `POST /v1/apple-pay/validate-merchant` sem erro. * **AP-04:** recusa. No sandbox, o token da Apple não permite forçar uma recusa. Demonstre o tratamento de recusa com o cartão `4444333322221112` em uma cobrança de cartão digitado, ou registre o cenário como não aplicável no sandbox. * **AP-05:** estorno de uma cobrança Apple Pay paga, com `refunded` e `charge.refunded`. * **AP-06:** recebimento do webhook `charge.paid`. ## Migração: quem já operava com certificado próprio Esta seção é para quem integrou pelo modelo anterior: conta no Apple Developer Program, Merchant ID próprio, domínio verificado no portal da Apple, Merchant Identity Certificate no seu backend e Payment Processing Certificate entregue à Finvia, que decifrava o token. Esse modelo continua disponível, mas novas integrações e contas migradas usam o fluxo pass-through desta página. ### O que muda | | Certificado próprio (antes) | Pass-through (agora) | | - | - | - | | Conta Apple Developer e Merchant ID | Obrigatórios, seus | Não são necessários: a relação com a Apple é do processador | | Verificação do domínio | No portal da Apple, com o arquivo `.txt` do seu Merchant ID em `/.well-known/` | Pela API da Finvia (Etapas 1 a 3), com o arquivo do processador no caminho **sem extensão**. O `.txt` antigo pode continuar no ar | | `onvalidatemerchant` | Resolvido no seu backend com o Merchant Identity Certificate | Chama `POST /v1/apple-pay/validate-merchant` com a chave `pk_` (Etapa 4) e devolve a sessão à Apple sem modificar | | Certificados | Payment Processing Certificate entregue à Finvia, renovação a cada 25 meses | Nenhum certificado, nada a renovar | | `supportedNetworks` | Visa, Mastercard, Amex, Discover | Apenas `visa` e `masterCard` (Elo em homologação) | | Moeda | Qualquer moeda da sua conta | Apenas `BRL` (`APPLE_PAY_CURRENCY_NOT_SUPPORTED`) | | `customer.document` na cobrança | Opcional | Obrigatório (`APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED`): o token da Apple não traz CPF/CNPJ, colete-o antes de abrir a folha de pagamento | | 3D Secure | Aplicado pela Finvia sobre o cartão decifrado | Não se aplica: `three_ds` vem nulo na resposta e nos webhooks | | `POST /v1/charges` | `paymentMethod.wallet` com o token na íntegra | Igual, sem mudança de formato | Continuam iguais: as chaves `sk_` e `pk_`, o parcelamento, os webhooks de cobrança (com `three_ds` nulo e a possibilidade do status `in_analysis`) e o rótulo da folha de pagamento, que vem do `total.label` do seu `ApplePaySession`. ### Ordem da virada O registro do primeiro domínio coloca a conta no modelo pass-through **no mesmo instante**. A partir dele, um token gerado pelo seu Merchant ID antigo é recusado pelo processador. Por isso, prepare tudo antes e faça os passos 3 a 5 na mesma janela. **1. Prepare o novo frontend, sem publicar** `onvalidatemerchant` da Etapa 4, `supportedNetworks: ['visa', 'masterCard']`, `currencyCode: 'BRL'`, coleta de CPF/CNPJ antes da folha de pagamento e `customer.document` na cobrança. **2. Deixe a rota do arquivo pronta** Prepare a rota que vai servir `/.well-known/apple-developer-merchantid-domain-association` em `text/plain`, sem redirect. O conteúdo vem no passo seguinte. **3. Registre cada hostname** Registre cada hostname onde o botão aparece (Etapa 1). Guarde `id` e `verificationFile.content`. **4. Hospede e valide** Hospede o arquivo (Etapa 2) e valide cada domínio até `verified` (Etapa 3). **5. Publique e teste** Publique o novo frontend e faça uma compra real de valor baixo. Para voltar ao modelo anterior depois da virada, fale com o suporte. Se você também vende pelo link de pagamento da Finvia, não há nada a fazer nele. ## Veja também > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Campos do objeto `wallet`. > [card] [Cartão de crédito](/guias/cobrancas/cartao-de-credito) > > Regras de cartão que valem para o Apple Pay. > [card] [Apple Pay on the Web](https://developer.apple.com/documentation/apple_pay_on_the_web) > > Documentação da Apple sobre o Apple Pay JS. > [card] [Diretrizes de interface do Apple Pay](https://developer.apple.com/design/human-interface-guidelines/apple-pay) > > Como exibir o botão. # Cartão de crédito Source: https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito Cobre com cartão digitado no checkout, à vista ou em até 12 parcelas, e trate aprovação e recusa na própria resposta. Na cobrança com cartão de crédito digitado, o cliente informa os dados do cartão no seu checkout e o seu servidor envia esses dados à Finvia na criação da cobrança. A aprovação ou a recusa volta **na própria resposta**, e o seu checkout já sabe se pode confirmar o pedido ou oferecer outra forma de pagamento. > [!NOTE] > > **Para o negócio:** o cartão permite parcelar em até 12 vezes e dá a resposta na própria criação da cobrança. Quando a compra é recusada, o campo `reason` explica o motivo, e o checkout pode sugerir outro cartão ou o Pix sem o cliente sair da página. ## Quando usar | Situação | Recomendação | | - | - | | Checkout com parcelamento | Cartão digitado com `installments` de 1 a 12 | | Primeira compra de um cliente | Cartão digitado. Se quiser recompra com um clique, registre o cartão depois ([Cartão salvo](/guias/cobrancas/cartao-salvo)) | | Cliente já tem cartão guardado na sua loja | [Cartão salvo](/guias/cobrancas/cartao-salvo) | | Checkout com iPhone ou Mac | [Apple Pay](/guias/cobrancas/apple-pay) | | Cobrança mensal sem o cliente presente | [Assinaturas](/guias/assinaturas/visao-geral) | | A sua conta exige autenticação do titular | Cartão com [3D Secure](/guias/3d-secure/visao-geral) | ## Como funciona O desenho abaixo mostra a cobrança com cartão digitado e os quatro resultados que podem voltar na resposta da criação. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant L as Seu checkout e servidor participant W as Seu receptor de webhooks end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant E as Adquirente e emissor end C->>L: Número, nome, validade, CVV e parcelas L->>F: POST /v1/charges · credit_card · installments 1 a 12 Note over F,E: Antes do adquirente, a Finvia aplica o antifraude e a regra de 3DS da conta alt Aprovada F->>E: Pede a autorização E-->>F: Autorizada F-->>L: 201 · paid · reason success L-->>C: Pedido confirmado F-)W: charge.paid else Recusada ou falha F-->>L: 201 · refused ou failed · motivo em reason L-->>C: Mostra o motivo e oferece outro cartão ou Pix F-)W: charge.refused ou charge.failed else Em análise ou pendente F-->>L: 201 · in_analysis ou pending L-->>C: Pedido aguardando confirmação F-)W: Desfecho depois · charge.updated, só na postbackUrl else threeDSMode managed e o banco pede verificação F-->>L: 201 · authentication_required · authenticationUrl L-->>C: Leva o comprador à authenticationUrl end ``` Uma recusa por 3D Secure obrigatório também chega no ramo de recusa, com `reason` começando em `3ds_`. O caminho com `authentication_required` continua no guia de [3DS gerenciado](/guias/3d-secure/gerenciado). **1. O cliente preenche o cartão no seu checkout** Número, nome impresso, validade, CVV e quantidade de parcelas. **2. Seu servidor cria a cobrança** Você chama `POST /v1/charges` com `paymentMethod.type` `credit_card` e os dados do cartão, usando a chave secreta. **3. A resposta traz o resultado** `status` `paid` (aprovada), `refused` (recusada) ou `failed` (falha no processamento). Em recusas, `reason` explica o motivo. A resposta também pode vir `in_analysis` (revisão manual do antifraude) ou, com 3DS gerenciado, `authentication_required`. **4. O checkout mostra o resultado** Aprovada: confirme o pedido. Recusada: mostre o motivo e ofereça outra forma de pagamento. **5. Os webhooks acompanham o pós-venda** `charge.paid`, `charge.refused` ou `charge.failed` registram o resultado nos endpoints e na `postbackUrl`. Estornos, bloqueios e alertas de chargeback chegam depois. ## Campos do cartão | Campo | Tipo | Obrigatório | Regra | | - | - | - | - | | `type` | string | Sim | `credit_card` | | `number` | string | Sim | Número do cartão, só com dígitos. Espaços são recusados com `400` | | `holderName` | string | Sim | Nome impresso no cartão | | `expirationMonth` | string | Sim | 2 caracteres. Ex.: `"03"` | | `expirationYear` | string | Sim | 4 caracteres. Ex.: `"2028"` | | `cvv` | string | Sim | Mínimo de 3 caracteres | | `installments` | integer | Sim | De `1` a `12` | | `threeDSMode` | string | Não | `managed` para o [3DS gerenciado](/guias/3d-secure/gerenciado) | | `browser` | object | Não | Dados do navegador para o 3DS (`userAgent` e `ipAddress` obrigatórios). Envie junto com `threeDSMode` | | `threeDS` | object | Não | Resultado de uma autenticação 3DS feita antes ([SDK](/guias/3d-secure/sdk) ou [via API](/guias/3d-secure/via-api)) | > [!WARNING] > > Mês e ano são **strings** com tamanho fixo. `"3"` e `"28"` são rejeitados. Envie `"03"` e `"2028"`. ## Regras de negócio | Regra | Detalhe | | - | - | | Parcelamento | De 1 a 12 parcelas (`installments`). A conta precisa ter taxa configurada para o número de parcelas | | Valor | Em reais: `"amount": 599.7` é R\$ 599,70. Mínimo `1` | | Resultado | Síncrono: `paid`, `refused` ou `failed` na resposta da criação. Também pode vir `in_analysis` ou `authentication_required` | | Motivo da recusa | Campo `reason` da resposta (ex.: `card_declined`) | | Produto físico | Se algum item for `physical`, `shippingAddress` é obrigatório (`postalCode`, `addressLine1`, `city`, `state`, `country`) | | 3D Secure | Pode ser exigido pela configuração da conta. Sem autenticação, a cobrança é recusada (ver [3D Secure](/guias/3d-secure/visao-geral)) | | Tentativas repetidas | Tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas: a listagem mostra só a principal | | Estorno | Total, só de cobrança `paid` ([Estorno](/guias/estorno)) | ### Recusa: resposta síncrona e notificação A recusa volta na resposta da criação, com `status` `refused` (ou `failed`) e o motivo em `reason`. O seu checkout deve tratar esse resultado ali mesmo, sem esperar webhook. Os webhooks complementam a resposta: | Situação | O que chega | | - | - | | Recusa ou falha na criação | `charge.refused` (status `refused`) ou `charge.failed` (status `failed`), no envelope padrão, para os endpoints do painel e a `postbackUrl`. Sai no máximo uma vez por cobrança | | Recusa ao final do 3DS gerenciado | `charge.refused` ou `charge.failed` nos endpoints e na `postbackUrl`, mais o `charge.updated` legado na `postbackUrl` | | Recusa ou falha informada depois pelo adquirente (cobrança que ficou `in_analysis` ou `pending`) | Só o `charge.updated` legado, na `postbackUrl`. Os endpoints do painel não recebem nada. O status final pode ser `failed` | | Cobrança recorrente de assinatura recusada | `subscription.payment_failed`. Não gera `charge.refused` nem `charge.failed` | O envelope padrão não traz o motivo da recusa. Ele aparece na resposta da criação, na consulta da cobrança e no `charge.updated`. Para cobranças que ficam em `in_analysis` ou `pending`, acompanhe pela `postbackUrl` ou consulte `GET /v1/charges/{id}`. ## Dados do cliente e IP O objeto `customer` da cobrança de cartão aceita estes campos: | Campo | Exemplo | Observação | | - | - | - | | `customer.name` | `Maria Souza` | Nome do cliente | | `customer.email` | `maria@email.com` | Obrigatório sem `id` e sem `phone` | | `customer.phone` | `+5511987654321` | Pode substituir o e-mail quando não há `id` | | `customer.document` | `{ "type": "cpf", "id": "52998224725" }` | Documento do cliente | | `customer.address.country` | `BRA` | ISO 3166-1 alpha-3 | | `customer.ipAddress` | `177.128.144.97` | IP do cliente no momento da compra | > [!TIP] > > **Para o desenvolvedor:** o IP do cliente é o do navegador, não o do seu servidor. Se a sua aplicação fica atrás de proxy ou balanceador, leia o IP no cabeçalho que o proxy repassa (ex.: `X-Forwarded-For`), conforme a configuração da sua infraestrutura. ## Segurança no checkout Nesta forma de pagamento, os dados completos do cartão passam pelo seu servidor, porque é ele que chama a API. Isso traz responsabilidades para a sua aplicação: * **Use HTTPS** em todas as páginas do checkout e em todas as chamadas, do navegador ao seu servidor e do seu servidor à API. * **Não grave** o número do cartão nem o CVV em banco de dados, arquivos ou caches. Use os dados só na chamada e descarte. * **Não registre em log** o corpo da requisição de cobrança sem mascarar `number` e `cvv`. Registre apenas os 6 primeiros e os 4 últimos dígitos, que a própria resposta devolve (`firstSix` e `lastFour`). * **Mantenha a chave secreta no servidor.** O navegador nunca chama `POST /v1/charges` direto. * **Para recompra**, use o [cofre de cartões](/guias/cofre-de-cartoes), que guarda o cartão na Finvia e devolve um identificador. > [!WARNING] > > Verifique com a sua área de segurança e conformidade os requisitos que se aplicam à sua empresa por trafegar dados de cartão no seu servidor. ```javascript theme={null} // Exemplo de log seguro: nunca registre number e cvv function logCobranca(payload, resposta) { const { number, cvv, ...cartaoSemDadosSensiveis } = payload.paymentMethod; console.log({ amount: payload.amount, paymentMethod: cartaoSemDadosSensiveis, chargeId: resposta.id, status: resposta.status, reason: resposta.reason, }); } ``` ## Passo a passo ### Cobrança parcelada de produto físico ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 599.7, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 3 }, "items": [ { "title": "Tênis de corrida", "type": "physical", "description": "Tamanho 38", "unit_price": 199.9, "quantity": 3 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "metadata": { "orderId": "ORD-3091" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 599.7, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 3 }, "items": [ { "title": "Tênis de corrida", "type": "physical", "description": "Tamanho 38", "unit_price": 199.9, "quantity": 3 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "metadata": { "orderId": "ORD-3091" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); async function cobrarCartao(pedido, cartao, ipCliente) { const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: pedido.total, currency: 'BRL', customer: { name: pedido.nome, email: pedido.email, document: { type: 'cpf', id: pedido.cpf }, ipAddress: ipCliente, }, paymentMethod: { type: 'credit_card', number: cartao.numero.replace(/\s/g, ''), holderName: cartao.nome, expirationMonth: cartao.mes.padStart(2, '0'), expirationYear: cartao.ano, cvv: cartao.cvv, installments: cartao.parcelas, }, items: pedido.itens, shippingAddress: pedido.endereco, metadata: { orderId: pedido.id }, postbackUrl: 'https://meusite.com.br/webhooks/finvia', }), }); const charge = await response.json(); switch (charge.status) { case 'paid': return { ok: true, chargeId: charge.id }; case 'refused': return { ok: false, motivo: charge.reason, chargeId: charge.id }; case 'authentication_required': // 3DS gerenciado: leve o comprador à URL recebida, sem alterá-la return { ok: false, autenticar: charge.authenticationUrl, chargeId: charge.id }; case 'in_analysis': case 'pending': // Aguarde o desfecho pela postbackUrl ou consulte a cobrança depois return { ok: false, aguardando: true, chargeId: charge.id }; default: // failed return { ok: false, motivo: charge.reason ?? 'Falha no processamento', chargeId: charge.id }; } } ``` ```python Python theme={null} import os import requests payload = { "amount": 599.7, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725", }, "ipAddress": "177.128.144.97", }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 3, }, "items": [ { "title": "Tênis de corrida", "type": "physical", "description": "Tamanho 38", "unit_price": 199.9, "quantity": 3, }, ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", }, "metadata": { "orderId": "ORD-3091", }, "postbackUrl": "https://meusite.com.br/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 599.7, 'currency' => 'BRL', 'customer' => [ 'name' => 'Maria Souza', 'email' => 'maria@email.com', 'document' => [ 'type' => 'cpf', 'id' => '52998224725', ], 'ipAddress' => '177.128.144.97', ], 'paymentMethod' => [ 'type' => 'credit_card', 'number' => '4444333322221111', 'holderName' => 'MARIA SOUZA', 'expirationMonth' => '10', 'expirationYear' => '2028', 'cvv' => '123', 'installments' => 3, ], 'items' => [ [ 'title' => 'Tênis de corrida', 'type' => 'physical', 'description' => 'Tamanho 38', 'unit_price' => 199.9, 'quantity' => 3, ], ], 'shippingAddress' => [ 'postalCode' => '01310100', 'addressLine1' => 'Av. Paulista, 1000', 'addressLine2' => 'Apto 51', 'neighborhood' => 'Bela Vista', 'city' => 'São Paulo', 'state' => 'SP', 'country' => 'BRA', ], 'metadata' => [ 'orderId' => 'ORD-3091', ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 599.7, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 3 }, "items": [ { "title": "Tênis de corrida", "type": "physical", "description": "Tamanho 38", "unit_price": 199.9, "quantity": 3 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "metadata": { "orderId": "ORD-3091" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 599.7, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 3 }, "items": [ { "title": "Tênis de corrida", "type": "physical", "description": "Tamanho 38", "unit_price": 199.9, "quantity": 3 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "metadata": { "orderId": "ORD-3091" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 599.7, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "ipAddress": "177.128.144.97" }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2028", "cvv": "123", "installments": 3 }, "items": [ { "title": "Tênis de corrida", "type": "physical", "description": "Tamanho 38", "unit_price": 199.9, "quantity": 3 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "metadata": { "orderId": "ORD-3091" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 599.7, "currency" => "BRL", "customer" => { "name" => "Maria Souza", "email" => "maria@email.com", "document" => { "type" => "cpf", "id" => "52998224725", }, "ipAddress" => "177.128.144.97", }, "paymentMethod" => { "type" => "credit_card", "number" => "4444333322221111", "holderName" => "MARIA SOUZA", "expirationMonth" => "10", "expirationYear" => "2028", "cvv" => "123", "installments" => 3, }, "items" => [ { "title" => "Tênis de corrida", "type" => "physical", "description" => "Tamanho 38", "unit_price" => 199.9, "quantity" => 3, }, ], "shippingAddress" => { "postalCode" => "01310100", "addressLine1" => "Av. Paulista, 1000", "addressLine2" => "Apto 51", "neighborhood" => "Bela Vista", "city" => "São Paulo", "state" => "SP", "country" => "BRA", }, "metadata" => { "orderId" => "ORD-3091", }, "postbackUrl" => "https://meusite.com.br/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ### Respostas possíveis > [tab] Aprovada > > ```json theme={null} > { > "id": "2vorkDcXyvzifL63YX09S9VqcnI", > "status": "paid", > "paymentDetails": { > "firstSix": "444433", > "lastFour": "1111", > "expirationMonth": "10", > "expirationYear": "2028", > "holderName": "MARIA SOUZA", > "installments": 3 > }, > "reason": "success", > "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q" > } > ``` > [tab] Recusada > > ```json theme={null} > { > "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE", > "status": "refused", > "paymentDetails": null, > "reason": "card_declined" > } > ``` > [tab] Em análise > > ```json theme={null} > { > "id": "2vorkAn5Ls6Is7Ma8Nu9AlRvWxY", > "status": "in_analysis", > "paymentDetails": null, > "reason": "antifraud_manual_review" > } > ``` > [tab] Sem endereço (400) > > ```json theme={null} > { > "message": "Shipping info must be provided for merchants selling physical items.", > "error": "Bad Request", > "statusCode": 400 > } > ``` > [!NOTE] > > `paymentDetails` é anulável. Trate o caso em que ele vem `null` e use `status` e `reason` para decidir o que mostrar ao cliente. `customerId` não vem quando a cobrança é barrada antes de chegar ao adquirente (antifraude ou 3DS). ## Cartões de teste No Modo Teste (chave `sk_test_`), a cobrança vai para um processador simulado e o resultado depende só do número do cartão. Envie o número só com dígitos. | Número | Resultado | `status` / `reason` | | - | - | - | | `4444333322221111` | Aprovado | `paid` / `success` | | `4444333322221112` | Recusado | `refused` / `card_declined` | | Qualquer número terminado em `2222` (ex.: `4444333322222222`) | Pendente | `pending` / `pending`. Fica pendente: não há confirmação posterior simulada | | Qualquer outro número | Aprovado | `paid` / `success` | Nome, CVV e validade não influenciam o resultado: use qualquer nome, CVV numérico de 3 dígitos e validade futura (mês com 2 dígitos, ex.: `05`, e ano com 4). O parcelamento de 1 a 12 vezes funciona igual, desde que a conta tenha taxa configurada para o número de parcelas. A recusa é síncrona e vem na própria resposta. > [!WARNING] > > Esses números só valem com a chave de teste. Com a chave de produção, a cobrança vai para a adquirente real. As regras de 3D Secure e de antifraude da sua conta continuam valendo no Modo Teste: se a conta exige 3DS ou tem antifraude ligado, a recusa pode vir dessas etapas, com `reason` começando em `3ds_` ou `antifraud_denied`. ## Estorno e chargeback * **Estorno:** uma cobrança paga pode ser estornada por `POST /v1/refunds`, sempre pelo valor total. O pedido vai à adquirente na hora, e o crédito aparece na fatura do comprador conforme o prazo do banco emissor. Você recebe `charge.refunded`. Veja [Estorno](/guias/estorno). * **Pré-chargeback:** quando o titular contesta a compra no emissor, a cobrança pode receber um alerta (`pre_chargeback`), avisado pelo `charge.pre_chargeback`. * **Bloqueio:** durante a disputa, a equipe Finvia pode bloquear a cobrança (`isBlocked: true`, status ainda `paid`), avisado pelo `charge.blocked`. * **Chargeback formalizado:** chega pelo `charge.updated` com `status: "chargeback"` na `postbackUrl` e, quando o valor é revertido do saldo, também pelo `charge.refunded`. O fluxo completo está em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `status` `refused` com `reason` | Recusa do emissor, do antifraude ou do processador | Mostre o motivo e ofereça outro cartão ou Pix | | `refused` com `reason` iniciando em `3ds_required` | A conta exige 3D Secure e a cobrança veio sem autenticação | Integre o [3D Secure](/guias/3d-secure/visao-geral) | | `400` de validação | `number` com espaços, `expirationMonth` ou `expirationYear` com tamanho errado, `cvv` curto, `installments` fora de 1 a 12 | Número só com dígitos, mês com 2 caracteres, ano com 4, CVV com pelo menos 3 e parcelas de 1 a 12 | | `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie o endereço de entrega | | `422` com `Fees not configured` | Conta sem taxa para cartão na moeda ou no número de parcelas | Fale com o suporte da Finvia | | `403` | Perfil do usuário que gerou a chave | Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave) | | Cobrança cobrada duas vezes | O POST foi reenviado depois de um timeout | Siga o [procedimento de timeout](/guias/cobrancas/visao-geral#timeout-na-criação) antes de repetir | ## Perguntas frequentes > [accordion] Preciso esperar um webhook para saber se o cartão foi aprovado? > > Não. Aprovação e recusa voltam na resposta da criação. Os webhooks `charge.paid`, `charge.refused` e `charge.failed` complementam a resposta. A exceção é a cobrança que fica `in_analysis` ou `pending`: o desfecho chega depois, pelo `charge.updated` na `postbackUrl` ou pela consulta. > [accordion] Quantas parcelas posso oferecer? > > De 1 a 12, desde que a sua conta tenha taxa configurada para o número de parcelas. A quantidade usada volta em `paymentDetails.installments`. > [accordion] Posso guardar o cartão do cliente para a próxima compra? > > Use o [cofre de cartões](/guias/cofre-de-cartoes) com `POST /v1/cards` e cobre depois com [cartão salvo](/guias/cobrancas/cartao-salvo). Não guarde número e CVV no seu banco de dados. > [accordion] Posso cobrar o cartão todo mês sem o cliente informar o CVV? > > Não pela rota de cobrança: ela exige o CVV em toda cobrança. Para cobrança recorrente, use [Assinaturas](/guias/assinaturas/visao-geral). > [accordion] Como testo uma recusa? > > No Modo Teste, use o cartão `4444333322221112`. A resposta vem `refused` com `reason` `card_declined` e o webhook `charge.refused` é enviado. Use uma conta sem 3DS obrigatório, para a recusa não vir da autenticação. ## Como testar Com a chave de teste (`sk_test_`) e os [cartões de teste](#cartões-de-teste), execute no [roteiro de homologação](/homologacao/roteiro): * **CHG-01:** cartão `4444333322221111` à vista, com `paid` e webhook `charge.paid`. * **CHG-02:** cartão parcelado (ex.: 3x), com `installments` refletido. * **CHG-03:** cartão `4444333322221112`, com `refused` na própria resposta e o webhook `charge.refused`. * **CHG-07:** estorno total. * **CHG-10:** item físico sem endereço (`400`) e com endereço (`201`). Se a sua conta usa 3D Secure, inclua também o cenário de 3DS da sua conta. ## Veja também > [card] [Cartão salvo](/guias/cobrancas/cartao-salvo) > > Recompra com um clique. > [card] [3D Secure](/guias/3d-secure/visao-geral) > > Autenticação do titular do cartão. > [card] [Estorno](/guias/estorno) > > Como devolver uma cobrança paga. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Todos os campos da rota. # Cartão salvo Source: https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo Cobre as próximas compras do cliente com um clique, usando um cartão já guardado no cofre da Finvia e pedindo só o CVV. Esta página trata da **cobrança** com um cartão que já está guardado. O cadastro e a gestão dos cartões (registrar, consultar status, listar e excluir) estão em [Cofre de cartões](/guias/cofre-de-cartoes). Com o cartão salvo, o cliente digita os dados do cartão uma única vez. Nas compras seguintes, o seu checkout mostra o cartão mascarado (ex.: `****1111`), o cliente informa só o CVV e a cobrança é feita com o identificador do cartão (`cardTokenId`). > [!NOTE] > > **Para o negócio:** o cartão salvo encurta o checkout de quem compra de novo, porque o cliente não precisa digitar número, nome e validade. O CVV continua sendo pedido em toda compra: esta forma de pagamento é para compras com o cliente presente. Para cobrar automaticamente todo mês, use Assinaturas. > [!WARNING] > > O cofre de cartões é **o mesmo para teste e produção**. Um `cardTokenId` criado durante a homologação também funciona com a chave de produção, e aí a mesma chamada cobra de verdade. Controle no seu sistema qual chave cada ambiente usa. ## Quando usar | Situação | Use cartão salvo? | Alternativa | | - | - | - | | Recompra em loja virtual (refil, consumíveis, delivery) | Sim | | | Upgrade ou compra adicional dentro de um app ou plataforma | Sim | | | Cobrança mensal fixa, sem o cliente presente | Não | [Assinaturas](/guias/assinaturas/visao-geral) | | Cobrança recorrente iniciada pela sua empresa | Não | [Assinaturas](/guias/assinaturas/visao-geral) | | Primeira compra, sem cartão guardado | Não | [Cartão de crédito](/guias/cobrancas/cartao-de-credito) | ### Cartão salvo ou assinatura? | | Cartão salvo | Assinatura | | - | - | - | | Quem inicia a cobrança | O cliente, no seu checkout | A Finvia, a cada ciclo do plano | | CVV | Obrigatório em toda cobrança | Não é pedido a cada ciclo | | Valor | Livre, definido em cada cobrança | Definido pelo plano | | Rota | `POST /v1/charges` com `cardTokenId` | `POST /v1/subscriptions` | | Uso típico | Recompra com um clique | Mensalidade, clube, SaaS | Os dois usam o mesmo cartão registrado: o `id` devolvido por `POST /v1/cards` serve tanto para a cobrança com um clique quanto para criar uma assinatura. ## Como funciona O desenho abaixo mostra as duas fases: guardar o cartão uma vez e, nas compras seguintes, cobrar pedindo só o CVV. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant L as Seu checkout e servidor end box rgb(234,243,255) Finvia participant F as Finvia API e cofre end box rgb(244,240,255) Fora da Finvia participant E as Adquirente e emissor end Note over C,E: Uma única vez · guardar o cartão no cofre C->>L: Digita número, nome, validade e CVV L->>F: POST /v1/cards · customerId + dados do cartão F->>E: Registra o cartão, sem cobrar nada F-->>L: 201 · id (o cardTokenId) · maskedNumber L->>L: Grava só o id e o ****1111 Note over C,E: Nas próximas compras · cobrar com um clique L->>F: GET /v1/cards?customerId=... F-->>L: Cartões do cliente · use só os active L-->>C: Mostra o cartão ****1111 e pede o CVV C->>L: Digita só o CVV L->>F: POST /v1/charges · cardTokenId + cvv + installments F->>E: Pede a autorização F-->>L: 201 · paid, refused ou failed · motivo em reason L-->>C: Confirma o pedido ou oferece outro cartão ou Pix ``` O cadastro do cartão não tem modo de teste e não cobra nada. Com a chave `sk_test_`, só a cobrança da segunda fase é simulada. **1. Tenha um cartão ativo no cofre** O cartão foi registrado com `POST /v1/cards` e já nasce `active`. O cadastro não faz nenhuma cobrança nem transação de validação. O seu sistema guardou o `id` do cartão e o número mascarado. Veja [Cofre de cartões](/guias/cofre-de-cartoes). **2. Na recompra, peça só o CVV** O checkout mostra o cartão mascarado e o cliente digita o CVV. **3. Cobre com cardTokenId e cvv** Seu servidor chama `POST /v1/charges` com `paymentMethod.type` `credit_card`, `cardTokenId`, `cvv` e `installments`. **4. Leia o resultado na resposta** O resultado volta na resposta, como no cartão digitado: `paid`, `refused` ou `failed`, com o motivo em `reason`. ## Regras de negócio | Regra | Detalhe | | - | - | | CVV | Obrigatório em toda cobrança com `cardTokenId`, mínimo de 3 caracteres. Sem ele: `400` `CVV is required when using cardTokenId` | | Cartão utilizável | Cartão revogado (excluído) ou expirado recebe `400` | | Identificador | O `cardTokenId` é o campo `id` da resposta de `POST /v1/cards` (não o campo `token`) | | Dono do cartão | O cartão pertence ao merchant da chave que o registrou e não pode ser usado por outro merchant ou subconta | | Parcelas | `installments` obrigatório, de `1` a `12` | | Dados do cartão | Com `cardTokenId`, os campos `number`, `holderName`, `expirationMonth` e `expirationYear` não são necessários | > [!WARNING] > > A cobrança com cartão salvo não acontece com o cliente ausente. Se o seu modelo é cobrar todo mês sem o cliente digitar o CVV, use [Assinaturas](/guias/assinaturas/visao-geral). > [!TIP] > > **Para o desenvolvedor:** não armazene o CVV. Peça ao cliente que digite o código a cada compra e envie direto na requisição. ### Modo Teste | O que você faz com a chave `sk_test_` | O que acontece | | - | - | | Cobrança com `cardTokenId` (`POST /v1/charges`) | É **simulada** e não movimenta dinheiro. O resultado segue as regras dos [cartões de teste](/guias/cobrancas/cartao-de-credito#cartões-de-teste) aplicadas ao número guardado. Como o cartão salvo normalmente é real, a cobrança de teste costuma sair `paid` | | Cadastro do cartão (`POST /v1/cards`) | Não tem modo de teste: o cartão é guardado no cofre e registrado na adquirente de verdade, mas **nada é cobrado** | | Assinaturas | Não têm modo de teste: as cobranças são reais, inclusive a validação de R\$ 1,00 do trial grátis | Para testar uma recusa no sandbox, use a cobrança com cartão digitado e o cartão de recusa `4444333322221112`. ## Passo a passo ### 1. Confirme que o cartão pode ser usado Antes de oferecer o cartão no checkout, liste os cartões do cliente com [`GET /v1/cards?customerId=...`](/referencia/cartoes/listar) e mostre só os que estão `active`. A cobrança recusa cartão `revoked` ou `expired`. Use a listagem, e não a consulta individual: hoje a consulta pode mostrar `active` para um cartão já excluído ou vencido. Detalhes em [Cofre de cartões](/guias/cofre-de-cartoes). ### 2. Cobre com um clique ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 89.9, "currency": "BRL", "customer": { "id": "2vorkDcXyvzifL63YX09S9VqcnI" }, "paymentMethod": { "type": "credit_card", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "cvv": "123", "installments": 1 }, "items": [ { "title": "Refil de filtro", "type": "physical", "description": "Refil trimestral", "unit_price": 89.9, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 89.9, "currency": "BRL", "customer": { "id": "2vorkDcXyvzifL63YX09S9VqcnI" }, "paymentMethod": { "type": "credit_card", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "cvv": "123", "installments": 1 }, "items": [ { "title": "Refil de filtro", "type": "physical", "description": "Refil trimestral", "unit_price": 89.9, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }' ``` ```javascript Node.js theme={null} // cobrar-cartao-salvo.mjs (Node.js 18+, ESM) const API_URL = 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); async function cobrarCartaoSalvo({ customerId, cardTokenId, cvv, pedido }) { const response = await fetch(`${API_URL}/v1/charges`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: pedido.total, currency: 'BRL', customer: { id: customerId }, paymentMethod: { type: 'credit_card', cardTokenId, cvv, installments: 1 }, items: pedido.itens, shippingAddress: pedido.endereco, postbackUrl: 'https://meusite.com.br/webhooks/finvia', }), }); return response.json(); // status: paid, refused ou failed, com reason } const charge = await cobrarCartaoSalvo({ customerId: '2vorkDcXyvzifL63YX09S9VqcnI', cardTokenId: '36OO3bcGjhPjjF3tzrqOGcmQuKo', cvv: '123', // digitado pelo cliente nesta compra pedido: { total: 89.9, itens: [{ title: 'Refil de filtro', type: 'physical', description: 'Refil trimestral', unit_price: 89.9, quantity: 1 }], endereco: { postalCode: '01310100', addressLine1: 'Av. Paulista, 1000', addressLine2: 'Apto 51', neighborhood: 'Bela Vista', city: 'São Paulo', state: 'SP', country: 'BRA', }, }, }); console.log(charge.id, charge.status, charge.reason); ``` ```python Python theme={null} import os import requests payload = { "amount": 89.9, "currency": "BRL", "customer": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", }, "paymentMethod": { "type": "credit_card", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "cvv": "123", "installments": 1, }, "items": [ { "title": "Refil de filtro", "type": "physical", "description": "Refil trimestral", "unit_price": 89.9, "quantity": 1, }, ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", }, "postbackUrl": "https://meusite.com.br/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 89.9, 'currency' => 'BRL', 'customer' => [ 'id' => '2vorkDcXyvzifL63YX09S9VqcnI', ], 'paymentMethod' => [ 'type' => 'credit_card', 'cardTokenId' => '36OO3bcGjhPjjF3tzrqOGcmQuKo', 'cvv' => '123', 'installments' => 1, ], 'items' => [ [ 'title' => 'Refil de filtro', 'type' => 'physical', 'description' => 'Refil trimestral', 'unit_price' => 89.9, 'quantity' => 1, ], ], 'shippingAddress' => [ 'postalCode' => '01310100', 'addressLine1' => 'Av. Paulista, 1000', 'addressLine2' => 'Apto 51', 'neighborhood' => 'Bela Vista', 'city' => 'São Paulo', 'state' => 'SP', 'country' => 'BRA', ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 89.9, "currency": "BRL", "customer": { "id": "2vorkDcXyvzifL63YX09S9VqcnI" }, "paymentMethod": { "type": "credit_card", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "cvv": "123", "installments": 1 }, "items": [ { "title": "Refil de filtro", "type": "physical", "description": "Refil trimestral", "unit_price": 89.9, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 89.9, "currency": "BRL", "customer": { "id": "2vorkDcXyvzifL63YX09S9VqcnI" }, "paymentMethod": { "type": "credit_card", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "cvv": "123", "installments": 1 }, "items": [ { "title": "Refil de filtro", "type": "physical", "description": "Refil trimestral", "unit_price": 89.9, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 89.9, "currency": "BRL", "customer": { "id": "2vorkDcXyvzifL63YX09S9VqcnI" }, "paymentMethod": { "type": "credit_card", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "cvv": "123", "installments": 1 }, "items": [ { "title": "Refil de filtro", "type": "physical", "description": "Refil trimestral", "unit_price": 89.9, "quantity": 1 } ], "shippingAddress": { "postalCode": "01310100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 51", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 89.9, "currency" => "BRL", "customer" => { "id" => "2vorkDcXyvzifL63YX09S9VqcnI", }, "paymentMethod" => { "type" => "credit_card", "cardTokenId" => "36OO3bcGjhPjjF3tzrqOGcmQuKo", "cvv" => "123", "installments" => 1, }, "items" => [ { "title" => "Refil de filtro", "type" => "physical", "description" => "Refil trimestral", "unit_price" => 89.9, "quantity" => 1, }, ], "shippingAddress" => { "postalCode" => "01310100", "addressLine1" => "Av. Paulista, 1000", "addressLine2" => "Apto 51", "neighborhood" => "Bela Vista", "city" => "São Paulo", "state" => "SP", "country" => "BRA", }, "postbackUrl" => "https://meusite.com.br/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ### 3. Trate o resultado A resposta tem o mesmo formato da cobrança com cartão digitado: `id`, `status`, `paymentDetails` e `reason`. Libere o pedido só com `paid`. Em `refused`, mostre o motivo e ofereça outro cartão ou Pix. Detalhes em [Cartão de crédito](/guias/cobrancas/cartao-de-credito). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` `CVV is required when using cardTokenId` | `cvv` ausente | Peça o CVV ao cliente em toda compra | | `400` com cartão salvo | Cartão revogado (excluído) ou expirado | Confira a listagem `GET /v1/cards?customerId=...` e peça um novo cartão | | `status` `refused` com `reason` | Recusa do emissor ou do antifraude | Mostre o motivo e ofereça outro cartão ou Pix | | Cartão não aceito em uma subconta | O cartão pertence ao merchant que o registrou | Registre o cartão com a chave da conta que vai cobrar | | Cobrança real durante a homologação | `cardTokenId` de teste usado com a chave de produção | O cofre é compartilhado: separe as chaves por ambiente no seu sistema | ## Perguntas frequentes > [accordion] Posso cobrar o cartão salvo sem pedir o CVV? > > Não. O CVV é obrigatório em toda cobrança com `cardTokenId`. Para cobrar sem o cliente presente, use [Assinaturas](/guias/assinaturas/visao-geral), que dispensam o CVV na recorrência. > [accordion] Posso parcelar uma compra com cartão salvo? > > Sim. Envie `installments` de `1` a `12`, como na cobrança com cartão digitado. > [accordion] Uma subconta pode usar o cartão registrado pela conta master? > > Não. O cartão pertence ao merchant da chave que o registrou e só pode ser usado por ele. > [accordion] O cadastro do cartão cobra algum valor do cliente? > > Não. `POST /v1/cards` guarda o cartão no cofre e o registra na adquirente sem nenhuma cobrança nem transação de validação. O cartão já nasce `active`. > [accordion] Como testo sem cobrar de verdade? > > Com a chave `sk_test_`, a cobrança com `cardTokenId` é simulada e não movimenta dinheiro. O cadastro do cartão é real, mas não cobra nada. Lembre que o mesmo `cardTokenId` gera cobrança real com a chave de produção. ## Como testar Execute o cenário **SUB-02** da seção "Cartão salvo e assinaturas" do [roteiro de homologação](/homologacao/roteiro): cobrança com `cardTokenId` e `cvv` usando a chave de teste, com status `paid`, comprovando que o CVV é coletado a cada cobrança. O registro do cartão (**SUB-01**) está em [Cofre de cartões](/guias/cofre-de-cartoes). ## Veja também > [card] [Cofre de cartões](/guias/cofre-de-cartoes) > > Registrar, consultar, listar e excluir cartões. > [card] [Assinaturas](/guias/assinaturas/visao-geral) > > Cobrança recorrente sem o cliente presente. > [card] [Criar cobrança](/referencia/cobrancas/criar) > > Referência de `POST /v1/charges`. > [card] [Cartão de crédito](/guias/cobrancas/cartao-de-credito) > > Cobrança com cartão digitado. # Pix Source: https://docs.fastpaybrasil.com/guias/cobrancas/pix Gere um QR Code Pix, mostre no checkout, receba a confirmação por webhook e concilie o pagamento. O Pix é o pagamento instantâneo do Brasil. Na Finvia, você cria a cobrança e recebe na resposta o código copia e cola e a imagem do QR Code para mostrar ao cliente. Quando o cliente paga no app do banco, a Finvia avisa o seu sistema por webhook e você libera o pedido. > [!NOTE] > > **Para o negócio:** o Pix é pago à vista, sem parcelamento, e o cliente paga no app do próprio banco. Você define por quanto tempo o QR Code vale: alguns minutos em um checkout com o cliente na tela, ou um ou mais dias em uma cobrança enviada por link ou mensagem. ## Quando usar | Situação | Recomendação | | - | - | | Checkout de loja virtual com o cliente na tela | Pix com validade curta, em segundos (mínimo de 15 minutos) | | Cobrança enviada por WhatsApp, e-mail ou link | Pix com validade em dias | | Venda de infoproduto com liberação automática do acesso | Pix, liberando o acesso ao receber `charge.paid` | | Cliente quer parcelar | Use [cartão de crédito](/guias/cobrancas/cartao-de-credito) | | Cobrança automática todo mês | Use [Assinaturas](/guias/assinaturas/visao-geral) | ## Como funciona O desenho abaixo mostra o caminho completo de uma cobrança Pix, do pedido à confirmação, e o que acontece quando o QR Code vence sem pagamento. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant L as Seu checkout e servidor participant W as Seu receptor de webhooks end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant B as Banco do comprador end C->>L: Finaliza o pedido e escolhe Pix L->>F: POST /v1/charges · type pix + validade do QR Code F-->>L: 201 · pending · copyPaste · qrCodeBase64 F-)W: charge.created e charge.pending L-->>C: Mostra o QR Code e o copia e cola alt Comprador paga dentro da validade C->>B: Paga no app do banco B->>F: Confirma o Pix F-)W: charge.paid (e charge.updated na postbackUrl) W->>F: GET /v1/charges/{id} F-->>W: status paid · endToEndId preenchido L-->>C: Checkout mostra o pedido pago e libera else A validade acaba sem pagamento Note over L,F: Pix vencido ou cancelado. O status final pode vir failed F-)W: charge.updated, só na postbackUrl L->>F: Sem postbackUrl · GET /v1/charges/{id} após a validade L-->>C: Pedido não liberado · novo Pix se ele voltar end ``` Os eventos chegam aos endpoints de webhook cadastrados no painel e à `postbackUrl` da cobrança. O `charge.updated` vai só para a `postbackUrl`: sem ela, a única forma de saber que um Pix venceu é consultar a cobrança. **1. Você cria a cobrança Pix** Seu servidor chama `POST /v1/charges` com `paymentMethod.type` `pix` e a validade do QR Code. **2. A resposta traz o QR Code** A resposta `201` vem com `status` `pending` e `paymentDetails` com o código copia e cola (`copyPaste`), a imagem do QR Code (`qrCodeBase64`) e o identificador `endToEndId`. **3. Você mostra o QR Code ao cliente** O checkout exibe a imagem e um botão para copiar o código. Os endpoints de webhook e a `postbackUrl` recebem `charge.created` e `charge.pending`. **4. O cliente paga no app do banco** Ele escaneia o QR Code ou cola o código no app do banco e confirma o pagamento. **5. A Finvia confirma por webhook** A cobrança passa para `paid` e o seu sistema recebe `charge.paid` (e, na `postbackUrl`, também o `charge.updated` legado). Confirme com `GET /v1/charges/{id}` e libere o pedido. ## Regras de negócio | Regra | Detalhe | | - | - | | Validade obrigatória | Envie `expirationInDays` ou `expirationInSeconds`. Um dos dois é obrigatório | | Validade em dias | `expirationInDays`, mínimo `1` | | Validade em segundos | `expirationInSeconds`, mínimo `900` (15 minutos) | | Valor | Em reais: `"amount": 49.9` é R\$ 49,90. Mínimo `1` | | Moeda | Somente `BRL` | | Taxa | A conta precisa ter taxa de Pix em BRL configurada. Sem ela, a API responde `422` `Fees not configured` | | Status na criação | `pending`. O pagamento é confirmado depois, por webhook | | Pix cancelado ou expirado | O status final pode vir `failed`. Esse desfecho chega só pelo `charge.updated` na `postbackUrl` ou pela consulta | | Estorno | Total, só de cobrança `paid`, pedido em até 90 dias do pagamento. Veja [Estorno](/guias/estorno) | > [!WARNING] > > Nunca libere o pedido com base na resposta da criação. O `pending` indica só que o QR Code foi gerado. Libere só depois de receber `charge.paid` e confirmar o status com `GET /v1/charges/{id}`. ### Como escolher a validade | Cenário | Sugestão | Campo | | - | - | - | | Checkout com o cliente na tela | 15 a 30 minutos | `"expirationInSeconds": 900` a `1800` | | Reserva de estoque ou ingresso | Tempo da reserva, a partir de 15 minutos | `expirationInSeconds` | | Cobrança por link ou mensagem | 1 a 3 dias | `"expirationInDays": 1` a `3` | Uma validade curta mantém o pedido e o estoque alinhados com o pagamento. Uma validade longa dá tempo para o cliente pagar quando puder. ## O que vem na resposta | Campo | Para que serve | | - | - | | `id` | Identificador da cobrança. Grave no seu pedido | | `status` | `pending` na criação | | `paymentDetails.copyPaste` | Código Pix copia e cola (BR Code EMV). O cliente cola no app do banco | | `paymentDetails.qrCodeBase64` | Imagem PNG 256x256 do QR Code, em data URI. Vai direto no `src` de uma tag `` | | `paymentDetails.endToEndId` | Identificador End to End do Pix, preenchido quando o pagamento é confirmado | | `paymentDetails.expiresAt` | Data e hora de expiração do Pix (opcional) | | `customerId` | ID do cliente criado ou reaproveitado | | `reason` | `null` em cobranças Pix criadas com sucesso | > [!TIP] > > **Para o desenvolvedor:** `qrCodeBase64` pode vir `null` ou ausente quando a imagem não pôde ser gerada (ou em cobranças criadas antes de o campo existir). Nesse caso, gere o QR Code no seu front-end a partir do `copyPaste`, com qualquer biblioteca de QR Code, ou mostre só o código copia e cola. ## Passo a passo ### 1. Crie a cobrança ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 149.9, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, "items": [ { "title": "Curso de Fotografia", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 149.9, "quantity": 1 } ], "metadata": { "orderId": "ORD-2048" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 149.9, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, "items": [ { "title": "Curso de Fotografia", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 149.9, "quantity": 1 } ], "metadata": { "orderId": "ORD-2048" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }' ``` ```javascript Node.js theme={null} // criar-pix.mjs (Node.js 18+, ESM) const API_URL = 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); async function criarPix(pedido) { const response = await fetch(`${API_URL}/v1/charges`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: pedido.total, currency: 'BRL', customer: { name: pedido.nome, email: pedido.email }, paymentMethod: { type: 'pix', expirationInSeconds: 1800 }, items: pedido.itens, metadata: { orderId: pedido.id }, postbackUrl: 'https://meusite.com.br/webhooks/finvia', }), }); const charge = await response.json(); // Grave charge.id no pedido antes de devolver o QR Code ao front-end return { chargeId: charge.id, copyPaste: charge.paymentDetails.copyPaste, qrCodeBase64: charge.paymentDetails.qrCodeBase64 ?? null, }; } const pix = await criarPix({ id: 'ORD-2048', total: 149.9, nome: 'Maria Souza', email: 'maria@email.com', itens: [ { title: 'Curso de Fotografia', type: 'digital', description: 'Acesso por 12 meses', unit_price: 149.9, quantity: 1 }, ], }); console.log(pix.chargeId, pix.copyPaste); ``` ```python Python theme={null} import os import requests payload = { "amount": 149.9, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725", }, "phone": "+5511987654321", "address": { "country": "BRA", }, }, "paymentMethod": { "type": "pix", "expirationInSeconds": 1800, }, "items": [ { "title": "Curso de Fotografia", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 149.9, "quantity": 1, }, ], "metadata": { "orderId": "ORD-2048", }, "postbackUrl": "https://meusite.com.br/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 149.9, 'currency' => 'BRL', 'customer' => [ 'name' => 'Maria Souza', 'email' => 'maria@email.com', 'document' => [ 'type' => 'cpf', 'id' => '52998224725', ], 'phone' => '+5511987654321', 'address' => [ 'country' => 'BRA', ], ], 'paymentMethod' => [ 'type' => 'pix', 'expirationInSeconds' => 1800, ], 'items' => [ [ 'title' => 'Curso de Fotografia', 'type' => 'digital', 'description' => 'Acesso por 12 meses', 'unit_price' => 149.9, 'quantity' => 1, ], ], 'metadata' => [ 'orderId' => 'ORD-2048', ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 149.9, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, "items": [ { "title": "Curso de Fotografia", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 149.9, "quantity": 1 } ], "metadata": { "orderId": "ORD-2048" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 149.9, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, "items": [ { "title": "Curso de Fotografia", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 149.9, "quantity": 1 } ], "metadata": { "orderId": "ORD-2048" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 149.9, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, "items": [ { "title": "Curso de Fotografia", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 149.9, "quantity": 1 } ], "metadata": { "orderId": "ORD-2048" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 149.9, "currency" => "BRL", "customer" => { "name" => "Maria Souza", "email" => "maria@email.com", "document" => { "type" => "cpf", "id" => "52998224725", }, "phone" => "+5511987654321", "address" => { "country" => "BRA", }, }, "paymentMethod" => { "type" => "pix", "expirationInSeconds" => 1800, }, "items" => [ { "title" => "Curso de Fotografia", "type" => "digital", "description" => "Acesso por 12 meses", "unit_price" => 149.9, "quantity" => 1, }, ], "metadata" => { "orderId" => "ORD-2048", }, "postbackUrl" => "https://meusite.com.br/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201`: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "pending", "paymentDetails": { "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo..." }, "reason": null, "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q" } ``` ### 2. Mostre o QR Code no checkout O seu back-end devolve ao front-end apenas o `copyPaste` e o `qrCodeBase64`. A chave secreta nunca vai para o navegador. ```html theme={null}

Ou copie o código e cole no app do seu banco:

Aguardando pagamento...

``` > [!TIP] > > **Para o desenvolvedor:** para atualizar a tela quando o cliente pagar, faça o front-end consultar o **seu** back-end a cada poucos segundos (ou use WebSocket). O seu back-end responde com o status que gravou ao receber `charge.paid`. O navegador nunca chama a API da Finvia com a chave secreta. ### 3. Receba os webhooks Os eventos de cobrança chegam aos endpoints do painel e à `postbackUrl` no envelope padrão (`id`, `event`, `livemode`, `data`), com as chaves de `data` em snake\_case. Os objetos internos ficam como foram gravados: `payment_details` do Pix vem em camelCase (`endToEndId`, `copyPaste`, `qrCodeBase64`) e `metadata` volta exatamente como você enviou. O exemplo abaixo é um `charge.paid`. ```json theme={null} { "id": "2xKq7Rm4TzW9bN3pL8cV1dY6hJe", "event": "charge.paid", "livemode": true, "data": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "paid", "psp_ref_id": "pix_e2e_abc123", "amount": 149.9, "currency": "BRL", "spread": 1.5, "anticipation_fee_estimated": 0, "net": 148.4, "merchant_id": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH", "payment_method": { "type": "pix" }, "payment_details": { "endToEndId": "E12345678202610271035abcdef12345", "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }, "metadata": { "orderId": "ORD-2048" }, "paid_at": "2026-10-27T10:35:00.000Z", "is_test": false, "created_at": "2026-10-27T10:30:00.000Z", "updated_at": "2026-10-27T10:35:00.000Z" } } ``` O exemplo mostra parte do objeto `data`. O payload completo está em [Webhooks de cobrança](/guias/webhooks/cobranca). Na `postbackUrl`, o pagamento gera também um `charge.updated` legado, em camelCase e sem `id`. ```javascript Node.js theme={null} // webhook-pix.mjs (Node.js 18+, ESM) import express from 'express'; const API_URL = 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); // Exemplo em memória. Em produção, grave as chaves no seu banco. const processados = new Set(); const jaProcessado = async (key) => processados.has(key); const marcarProcessado = async (key) => { processados.add(key); }; async function consultarCobranca(id) { const res = await fetch(`${API_URL}/v1/charges/${id}`, { headers: { Authorization: `Basic ${credentials}` }, }); const texto = await res.text(); return texto ? JSON.parse(texto) : null; } // Troque pela liberação do pedido no seu sistema async function liberarPedidoPorCobranca(chargeId) { console.log('liberar', chargeId); } const app = express(); app.use(express.json()); app.post('/webhooks/finvia', async (req, res) => { const { id, event, data } = req.body; res.status(200).send('OK'); // responda rápido e processe em seguida // Envelope padrão: a chave de deduplicação é o id do evento if (!id) return; // charge.updated (sem id) é tratado à parte if (await jaProcessado(id)) return; if (event === 'charge.paid') { // Confirme na API antes de liberar: os webhooks não têm assinatura const charge = await consultarCobranca(data.id); // GET /v1/charges/{id} if (charge?.status === 'paid') { await liberarPedidoPorCobranca(charge.id); } } await marcarProcessado(id); }); app.listen(3000); ``` Para descartar eventos repetidos, siga a [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos), que cobre também o `charge.updated`. Depois de criado, um Pix pode passar pelos status abaixo. Cada seta mostra o que provoca a mudança e o aviso que o seu sistema recebe. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB CRI["POST /v1/charges
type pix"]:::lojista PEN(["pending
QR Code gerado"]):::alerta PAID(["paid
pago"]):::ok FAIL(["failed
cancelado ou expirado"]):::erro BLK(["paid + isBlocked
bloqueado por MED"]):::alerta RFD(["refunded
devolvido"]):::neutro DESB(["paid
bloqueio retirado"]):::ok CRI -->|"charge.created
charge.pending"| PEN PEN ==>|"comprador pagou
charge.paid"| PAID PEN -->|"venceu ou foi cancelado
charge.updated
só na postbackUrl"| FAIL PAID -->|"estorno em até
90 dias do pagamento
charge.refunded"| RFD PAID -->|"MED pedido pelo
banco do pagador
charge.blocked"| BLK BLK -->|"devolução aceita
charge.refunded"| RFD BLK -.->|"devolução recusada
sem webhook: consulte"| DESB classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` O estorno e o MED estão detalhados nas seções seguintes desta página e em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ## Conciliação Conciliar é conferir que cada pedido pago no seu sistema corresponde a um Pix recebido, com o valor certo. | Dado | Onde está | Uso na conciliação | | - | - | - | | `id` da cobrança | Resposta, webhook, consulta | Chave principal entre o seu pedido e a Finvia | | Número do seu pedido | `metadata.orderId`, igual no webhook, na consulta e na listagem | Liga o evento ao pedido | | `endToEndId` | `paymentDetails` (consulta) ou `payment_details` (webhook) | Identificador End to End do Pix | | `amount` e `net` | Webhook e consulta | Valor bruto e valor líquido, em reais | | `paid_at` / `paidAt` | Webhook / consulta | Data e hora do pagamento | Para conferir em lote, use [`GET /v1/charges`](/referencia/cobrancas/listar) com `status=paid`, `createdAtStart` e `createdAtEnd` no dia desejado, paginando por `page` e `size`. Para achar um Pix pelo `endToEndId`, use `searchFor`. ## Estorno de Pix Uma cobrança Pix paga pode ser estornada por `POST /v1/refunds`. O estorno é uma devolução Pix do pagamento original, sempre do valor total, enviada na hora. Quando aceita, o dinheiro costuma chegar em segundos na conta de origem. Pelas regras do Pix, a devolução precisa ser pedida em até 90 dias do pagamento: depois disso, o banco pode recusar. A cobrança vai para `refunded` e o seu sistema recebe `charge.refunded`. Detalhes em [Estorno](/guias/estorno). ## MED O MED (Mecanismo Especial de Devolução) é o mecanismo do Pix que permite à instituição do pagador pedir a devolução de um Pix em caso de suspeita de fraude ou falha operacional. Quando a Finvia é notificada de um MED sobre um Pix pago, a equipe Finvia bloqueia a cobrança enquanto o caso é analisado: * O `status` continua `paid` e a cobrança passa a ter `isBlocked: true`, `blockedAt` e `blockedReason`. * O evento `charge.blocked` vai aos endpoints de webhook e à `postbackUrl` (que recebe também o `charge.updated`). * O valor já liquidado da venda sai do saldo disponível e vai para o saldo bloqueado. * Se a devolução for aceita, a cobrança fica `refunded` e você recebe `charge.refunded`. Se for recusada, o bloqueio é retirado, **sem webhook**: acompanhe pela consulta. O fluxo completo, o envio da defesa e os desfechos estão em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` de validação | `expirationInSeconds` menor que `900`, ou nenhum campo de validade enviado | Envie `expirationInSeconds` a partir de `900` ou `expirationInDays` a partir de `1` | | `422` com `Fees not configured` | A conta não tem taxa de Pix em BRL | Fale com o suporte da Finvia | | Imagem do QR Code quebrada | `qrCodeBase64` veio `null` ou ausente | Gere o QR Code a partir do `copyPaste` ou mostre só o código | | Pedido liberado sem pagamento | Liberação feita com base no `pending` da criação | Libere só com `charge.paid` confirmado por `GET /v1/charges/{id}` | | Pedido liberado duas vezes | O mesmo evento chegou mais de uma vez, ou pelos dois canais | Aplique a [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos) | | Pedido fica pendente para sempre | Pix expirado ou cancelado, sem `postbackUrl` | Informe `postbackUrl` ou consulte a cobrança depois da validade | ## Perguntas frequentes > [accordion] Posso usar expirationInDays e expirationInSeconds juntos? > > Um dos dois é obrigatório. Envie só o que corresponde à sua regra: segundos para checkout com o cliente na tela, dias para cobranças por link. > [accordion] Qual a validade mínima de um Pix? > > 15 minutos: `expirationInSeconds` tem mínimo `900`. Em dias, o mínimo é `1`. > [accordion] O Pix aceita parcelamento? > > Não. O Pix é pago à vista. Para parcelar, use [cartão de crédito](/guias/cobrancas/cartao-de-credito). > [accordion] Como sei que o cliente pagou? > > Pelo webhook `charge.paid`. Ao receber, confirme o status com `GET /v1/charges/{id}` antes de liberar o pedido. > [accordion] Como testo um Pix pago sem pagar de verdade? > > Crie a cobrança com a chave `sk_test_`. Cerca de 5 segundos depois, ela passa sozinha para `paid` e você recebe `charge.paid`. Não tente pagar o código de teste em um app de banco. ## Como testar No Modo Teste (chave `sk_test_`), o Pix é confirmado automaticamente. Não há nada para pagar nem botão de simulação. **1. Crie a cobrança com a chave de teste** Use `paymentMethod: { "type": "pix", "expirationInSeconds": 900 }` (ou `expirationInDays`). **2. Confira a resposta** Vem `status: "pending"` com `copyPaste` e `qrCodeBase64` fictícios. Não tente pagar esse código. **3. Aguarde cerca de 5 segundos** A cobrança passa sozinha para `paid`: `paidAt` é preenchido e `paymentDetails.endToEndId` recebe um valor de teste. **4. Confira os eventos** Os endpoints recebem `charge.created` e `charge.pending` na criação e `charge.paid` na confirmação, com `livemode: false`. A `postbackUrl`, se informada, também é notificada. Confirme com `GET /v1/charges/{id}` usando a mesma chave de teste. > [!NOTE] > > No sandbox todo Pix é aprovado: não dá para simular expiração ou falha. Para testar o tratamento de outros status, use [`POST /v1/charges/{id}/resend-webhook`](/referencia/cobrancas/reenviar-webhook-teste), que dispara um evento simulado sem alterar a cobrança. Se, em casos raros, a cobrança não virar `paid` em alguns segundos, gere outra. Cenários do [roteiro de homologação](/homologacao/roteiro): * **CHG-04 (Pix gerado):** cobrança com `pending`, resposta com o copia e cola e webhook `charge.pending`. * **CHG-05 (Pix pago):** o webhook `charge.paid` chega com o mesmo `id` devolvido na criação. * **CHG-07 (estorno):** estorno total da cobrança paga, com `charge.refunded`. * **CHG-08 e CHG-09:** recebimento e simulação de webhook. ## Veja também > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Formato completo dos eventos. > [card] [Estorno](/guias/estorno) > > Como devolver um Pix pago. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > Contestações e bloqueio preventivo. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Todos os campos da rota. # Como funcionam as cobranças Source: https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral O que é uma cobrança, quais formas de pagamento existem, como escolher entre elas e como acompanhar cada cobrança do pedido ao pagamento. A cobrança (charge) é o pedido de pagamento que o seu cliente vai pagar. Toda venda feita pela API da Finvia nasce de uma única rota, `POST /v1/charges`, e depois é acompanhada pela resposta da criação, pelos webhooks e pela consulta da cobrança. Com esse ciclo claro, a integração libera o pedido só quando ele foi pago e não deixa de liberar um pedido pago. > [!NOTE] > > **Para o negócio:** com uma mesma integração você recebe por Pix, cartão de crédito digitado, cartão salvo e Apple Pay, e pode dividir o valor entre contas (split). A forma de pagamento muda só um bloco da requisição, o `paymentMethod`. O restante (valor, cliente, itens, endereço) é igual para todas. ## Quando usar | Situação | O que usar | | - | - | | Venda avulsa em loja virtual, com o cliente no checkout | `POST /v1/charges` com Pix ou cartão | | Recompra rápida de um cliente que já comprou com cartão | `POST /v1/charges` com cartão salvo (`cardTokenId` + `cvv`) | | Cobrança automática todo mês, sem o cliente presente | [Assinaturas](/guias/assinaturas/visao-geral). A rota de cobrança exige o CVV do comprador em toda cobrança com cartão | | Venda com comissão para outra conta (marketplace, plataforma) | `POST /v1/charges` com `split` ([Split](/guias/fast-connect/split)) | | Desfazer uma venda paga | [Estorno](/guias/estorno) | ## Formas de pagamento O campo `paymentMethod.type` define a forma de pagamento. Cartão digitado, cartão salvo e Apple Pay usam o mesmo `type` (`credit_card`) e se diferenciam pelos campos que vão junto. | Forma | `type` | Campos que identificam | Guia | | - | - | - | - | | Pix | `pix` | `expirationInDays` ou `expirationInSeconds` | [Pix](/guias/cobrancas/pix) | | Cartão de crédito digitado | `credit_card` | `number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`, `installments` | [Cartão de crédito](/guias/cobrancas/cartao-de-credito) | | Cartão salvo | `credit_card` | `cardTokenId`, `cvv`, `installments` | [Cartão salvo](/guias/cobrancas/cartao-salvo) | | Apple Pay | `credit_card` | `wallet`, `installments` | [Apple Pay](/guias/cobrancas/apple-pay) | ### Qual escolher em cada situação | Se o seu cenário é... | Forma indicada | Por quê | | - | - | - | | Cliente quer pagar à vista | Pix | A resposta traz o QR Code e o código copia e cola. O pagamento é confirmado por webhook | | Cliente quer parcelar | Cartão de crédito | Aceita de 1 a 12 parcelas (`installments`) | | Você precisa da aprovação na própria resposta | Cartão de crédito | Aprovação e recusa voltam na resposta da criação | | Cobrança enviada por link ou mensagem, para o cliente pagar depois | Pix com validade em dias | `expirationInDays` mantém o QR Code válido por um ou mais dias | | Cliente recorrente que já tem cartão guardado na sua loja | Cartão salvo | O cliente informa só o CVV | | Checkout web com público que usa iPhone ou Mac | Apple Pay | O cliente paga com o cartão da Wallet, sem digitar dados. Só em `BRL` | | Cobrança fixa todo mês | Assinaturas | Cobra a cada ciclo sem o cliente presente | > [!NOTE] > > A lista do que está habilitado para a sua conta, por moeda, vem de [`GET /v1/payment-methods`](/referencia/meios-de-pagamento/listar). Para cobrar, a conta também precisa ter taxa configurada para o método e a moeda: sem ela, a API responde `422` `Fees not configured`. O desenho abaixo resume a tabela: com duas ou três perguntas sobre o seu cenário, você chega à forma de pagamento indicada. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Cliente pronto para pagar"]):::comprador Q1{"Cobra todo mês, sem
o cliente presente?"}:::decisao ASS["Assinaturas
POST /v1/subscriptions"]:::neutro Q2{"Quer parcelar ou precisa
da aprovação na hora?"}:::decisao Q3{"Paga agora, com
o checkout aberto?"}:::decisao PIXS["Pix com validade curta
expirationInSeconds 900 ou mais"]:::neutro PIXD["Pix com validade em dias
expirationInDays 1 ou mais"]:::neutro Q4{"Já tem cartão
salvo na loja?"}:::decisao SALVO["Cartão salvo
cardTokenId + cvv"]:::neutro Q5{"Usa iPhone ou Mac
e paga em reais?"}:::decisao AP["Apple Pay
wallet"]:::neutro CC["Cartão digitado
number, holderName, cvv..."]:::neutro INI --> Q1 Q1 -->|"sim"| ASS Q1 -->|"não"| Q2 Q2 -->|"não, paga à vista"| Q3 Q3 -->|"sim"| PIXS Q3 -->|"não, recebe por link"| PIXD Q2 -->|"sim"| Q4 Q4 -->|"sim"| SALVO Q4 -->|"não"| Q5 Q5 -->|"sim"| AP Q5 -->|"não"| CC classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Cartão digitado, cartão salvo e Apple Pay usam o mesmo `type` (`credit_card`) e aceitam de 1 a 12 parcelas. O Pix é sempre à vista. O desenho abaixo mostra o caminho comum a toda cobrança, da criação até a liberação do pedido, e o que fazer com cada status da resposta. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB SRV["Seu servidor
POST /v1/charges"]:::lojista API["Finvia API"]:::finvia D{"Qual status veio
na resposta?"}:::decisao PAID(["paid
cartão aprovado"]):::ok REF(["refused / failed
motivo em reason"]):::erro PEN(["pending
mostre o QR Code Pix"]):::alerta AN(["in_analysis
revisão do antifraude"]):::alerta AUT(["authentication_required
abra a authenticationUrl"]):::alerta OUTRA["Ofereça outro cartão
ou outra forma de pagamento"]:::neutro EV[["Webhooks
endpoints ou postbackUrl"]]:::evento GET["Seu servidor
GET /v1/charges/{id}"]:::lojista Q{"Status é paid?"}:::decisao LIB(["Libera o pedido"]):::ok ESP["Não libera ainda
continua ouvindo os webhooks"]:::neutro SRV ==>|"1. cria a cobrança"| API API ==>|"2. responde 201"| D D --> PAID D --> REF D --> PEN D --> AN D --> AUT REF --> OUTRA PEN -.->|"3. desfecho depois"| EV AN -.-> EV AUT -.-> EV PAID ==> GET EV -.->|"4. avisa o seu sistema"| GET GET ==>|"5. confere"| Q Q ==>|"sim"| LIB Q -->|"não"| ESP classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Depois de `paid`, a cobrança ainda pode ser bloqueada ou mudar para `refunded`, `pre_chargeback` ou `chargeback`. Por isso o receptor de webhooks continua ativo mesmo depois de liberar o pedido. ## Como funciona **1. Seu servidor cria a cobrança** Você chama `POST /v1/charges` com a chave secreta, informando valor, moeda, cliente, itens e forma de pagamento. Guarde o `id` devolvido: ele identifica a cobrança em todas as etapas seguintes. **2. A resposta síncrona diz o que fazer agora** No cartão, a resposta já traz o resultado (`paid`, `refused` ou `failed`), ou `in_analysis` quando o antifraude manda para revisão manual. No Pix, traz o QR Code com status `pending`. Com 3D Secure gerenciado, pode vir `authentication_required` com a `authenticationUrl` para o comprador se autenticar. **3. Os webhooks contam o que aconteceu depois** Mudanças posteriores (Pix pago, estorno, bloqueio, alerta de chargeback) chegam por webhook, uma notificação que a Finvia envia ao seu sistema. Quais eventos vão aos endpoints do painel e quais vão à `postbackUrl` está na [tabela de eventos por canal](/guias/webhooks/visao-geral#eventos-por-canal). **4. Seu sistema confirma e libera o pedido** Antes de liberar produto ou acesso, confirme o status com [`GET /v1/charges/{id}`](/referencia/cobrancas/consultar). Os webhooks não têm assinatura, então a consulta à API é a sua confirmação. ## Ciclo de vida da cobrança | Status | Significado | De onde vem | | - | - | - | | `pending` | Aguardando pagamento (ex.: Pix gerado) | Resposta da criação, `charge.pending` | | `paid` | Pago com sucesso | Resposta da criação (cartão), `charge.paid` | | `refused` | Recusado (emissor, antifraude ou 3DS obrigatório) | Resposta da criação, `charge.refused` | | `failed` | Falha no processamento | Resposta da criação, `charge.failed` | | `in_analysis` | Em revisão manual do antifraude | Resposta da criação. O desfecho chega pelo `charge.updated` na `postbackUrl` ou pela consulta | | `authentication_required` | Aguardando autenticação do comprador | Resposta da criação com 3DS gerenciado ([3DS gerenciado](/guias/3d-secure/gerenciado)) | | `refunded` | Estornado | Estorno concluído, `charge.refunded` | | `pre_chargeback` | Alerta de contestação recebido antes da disputa formal | `charge.pre_chargeback` | | `chargeback` | Chargeback formalizado | `charge.updated` na `postbackUrl` ([Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med)) | Além do status, uma cobrança paga pode ficar **bloqueada** durante uma disputa (MED no Pix ou chargeback no cartão). O status continua `paid` e o bloqueio aparece em `isBlocked` na consulta e no evento `charge.blocked`. O detalhamento de cada status está em [Status de cobrança](/anexos/status-de-cobranca). > [!WARNING] > > Trate `pending` como "ainda não pago". Libere o pedido só com `paid` confirmado por `GET /v1/charges/{id}`. Uma cobrança `paid` ainda pode ser bloqueada ou mudar depois para `refunded`, `pre_chargeback` ou `chargeback`, por isso o seu sistema precisa continuar ouvindo os webhooks. ## O que vem na resposta e o que vem por webhook | Informação | Resposta da criação (síncrona) | Webhook | | - | - | - | | `id` da cobrança | Sim | Sim (`data.id`) | | Aprovação ou recusa do cartão, com `reason` | Sim | `charge.paid`, `charge.refused` ou `charge.failed`. O motivo da recusa não vem no envelope padrão | | QR Code e copia e cola do Pix | Sim (`paymentDetails`) | Também em `payment_details` | | Confirmação de pagamento do Pix | Não | `charge.paid` | | Desfecho de uma cobrança `in_analysis` ou `pending` no cartão | Não | `charge.updated`, só na `postbackUrl`. Ou consulte a cobrança | | Estorno concluído | Não (o estorno tem resposta própria) | `charge.refunded` | | Bloqueio por MED ou chargeback | Não | `charge.blocked` (endpoints e `postbackUrl`) | | Alerta de pré-chargeback | Não | `charge.pre_chargeback` (endpoints e `postbackUrl`) | | Chargeback formalizado | Não | `charge.updated` com `status: "chargeback"`, só na `postbackUrl` | | Valor líquido (`net`) e spread aplicado (`spread`) | Não | Sim, e também na consulta | A resposta da criação traz `id`, `status`, `paymentDetails` e `reason`, mais `authenticationUrl` e `customerId` em alguns casos. Os detalhes completos da cobrança (valor líquido, cliente, metadata, split, datas) vêm na consulta e nos webhooks. ## Regras de negócio | Regra | Detalhe | | - | - | | Valor em reais | `"amount": 10` significa R\$ 10,00. Mínimo: `1` | | Campos obrigatórios | `amount`, `currency`, `customer`, `paymentMethod`, `items` | | Cliente | Informe o `id` de um cliente já cadastrado ou envie `name` + `email` (ou `phone`) para criar ou localizar o cliente na mesma chamada | | Itens físicos | Se algum item for `physical`, `shippingAddress` é obrigatório | | Endereço de entrega | Obrigatórios: `postalCode`, `addressLine1`, `city`, `state` e `country` (alpha-3, ex.: `BRA`). `addressLine2` e `neighborhood` são opcionais | | Parcelas | `installments` de `1` a `12` | | Permissão da chave | Chave gerada por usuário com perfil Desenvolvedor recebe `403` ao criar cobrança | | Idempotência | A API não aceita `Idempotency-Key`: cada chamada cria uma cobrança nova | > [!WARNING] > > Enviar o valor em centavos multiplica a cobrança por 100. `1000` gera uma cobrança de R\$ 1.000,00, e não de R\$ 10,00. ### Itens físicos e digitais O `type` de cada item diz se você entrega algo pelo correio ou transportadora (`physical`) ou se entrega acesso, arquivo ou serviço online (`digital`). * **Produto digital** (curso, ebook, software): envie `items[].type` `digital`, sem `shippingAddress`. * **Produto físico** (roupa, eletrônico, cosmético): envie `items[].type` `physical` e o `shippingAddress`. Se quiser, envie também `trackingInfo` com o código e a situação do envio (`awaiting_shipment`, `on_the_way` ou `delivered`). Se algum item for `physical` e o corpo não trouxer `shippingAddress`, a API responde `400` com a mensagem literal `Shipping info must be provided for merchants selling physical items.`, antes de criar a cobrança. A regra depende só dos itens enviados. ### Metadata `metadata` é um objeto livre onde você guarda informações suas na cobrança, como o número do pedido. Ele volta na consulta e nos webhooks, o que ajuda a ligar o evento recebido ao pedido do seu sistema. ```json theme={null} { "metadata": { "orderId": "ORD-123", "productId": "PROD-456" } } ``` Escreva as chaves de `metadata` em camelCase (`orderId`) ou com uma palavra só (`pedido`). Assim elas voltam iguais em todos os canais, e todos os exemplos desta documentação seguem essa regra. > [!NOTE] > > Chaves com sublinhado (snake\_case, como `order_id`) mudam de formato conforme o canal. Nos webhooks do envelope padrão (`charge.paid`, `charge.refunded` e os demais), elas voltam exatamente como foram enviadas (`order_id`). Nas respostas de `GET /v1/charges` e `GET /v1/charges/{id}` e no `charge.updated` legado, voltam convertidas para camelCase (`orderId`). Se a sua integração já usa snake\_case, leia os dois formatos. ### Timeout na criação A API não aceita cabeçalho de idempotência e não busca cobranças por `metadata`. Se a chamada de criação der timeout, siga esta ordem: **1. Não reenvie o POST de imediato** Se a primeira chamada chegou, um novo POST cria uma segunda cobrança. No cartão, isso é cobrança em dobro. **2. Procure o charge.created** Com um endpoint de webhook cadastrado, o `charge.created` chega assim que a cobrança é gravada e traz o `id` e a `metadata` como foram enviadas. É a forma mais confiável de recuperar o `id`. **3. Busque na listagem** `GET /v1/charges?createdAtStart=AAAA-MM-DD&createdAtEnd=AAAA-MM-DD&searchFor=&size=50`, com a mesma chave usada na criação. Compare `metadata` e `amount` do seu lado. **4. Só então crie de novo** Se nada for encontrado, a cobrança não foi criada e é seguro tentar de novo. Use um timeout de cliente generoso (por exemplo, 60 segundos): o cartão é processado de forma síncrona. Detalhes em [Idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia#idempotência) e em [Listar cobranças](/referencia/cobrancas/listar). ### postbackUrl `postbackUrl` é uma URL sua, informada na própria cobrança, que recebe de forma **assíncrona** os eventos dessa cobrança. Ela não muda a resposta da criação. * Recebe os mesmos eventos de cobrança que os endpoints do painel, no envelope padrão: `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback` e `charge.blocked`. Não há filtro de eventos nesse canal. * Recebe também o `charge.updated` legado, que vai **só** para a `postbackUrl`, em camelCase e sem `id` nem `livemode`. Ele avisa mudanças informadas depois pelo adquirente (pagamento, recusa ou falha assíncrona, estorno, chargeback), o fim do 3DS gerenciado com recusa, o bloqueio e o alerta de pré-chargeback. * Se a mesma URL estiver cadastrada como endpoint e como `postbackUrl`, ela recebe cada evento duas vezes. Sem `postbackUrl`, você não recebe o desfecho de cobranças que ficaram em `in_analysis` nem o aviso de chargeback formalizado. Os formatos estão na [tabela de eventos por canal](/guias/webhooks/visao-geral#eventos-por-canal). ## Passo a passo Exemplo de uma cobrança Pix para um produto digital, com metadata e postback. ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 100, currency: 'BRL', customer: { name: 'Joao Silva', email: 'joao@email.com' }, paymentMethod: { type: 'pix', expirationInDays: 1 }, items: [ { title: 'Produto XYZ', type: 'digital', description: 'Descrição do produto', unit_price: 100, quantity: 1 }, ], metadata: { orderId: 'ORD-123' }, postbackUrl: 'https://meusite.com.br/webhooks/finvia', }), }); const charge = await response.json(); // Grave charge.id no pedido ORD-123 antes de qualquer outra coisa ``` ```python Python theme={null} import os import requests payload = { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725", }, "phone": "+5511987654321", "address": { "country": "BRA", }, }, "paymentMethod": { "type": "pix", "expirationInDays": 1, }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1, }, ], "metadata": { "orderId": "ORD-123", }, "postbackUrl": "https://meusite.com.br/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 100, 'currency' => 'BRL', 'customer' => [ 'name' => 'Joao Silva', 'email' => 'joao@email.com', 'document' => [ 'type' => 'cpf', 'id' => '52998224725', ], 'phone' => '+5511987654321', 'address' => [ 'country' => 'BRA', ], ], 'paymentMethod' => [ 'type' => 'pix', 'expirationInDays' => 1, ], 'items' => [ [ 'title' => 'Produto XYZ', 'type' => 'digital', 'description' => 'Descrição do produto', 'unit_price' => 100, 'quantity' => 1, ], ], 'metadata' => [ 'orderId' => 'ORD-123', ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 100, "currency" => "BRL", "customer" => { "name" => "Joao Silva", "email" => "joao@email.com", "document" => { "type" => "cpf", "id" => "52998224725", }, "phone" => "+5511987654321", "address" => { "country" => "BRA", }, }, "paymentMethod" => { "type" => "pix", "expirationInDays" => 1, }, "items" => [ { "title" => "Produto XYZ", "type" => "digital", "description" => "Descrição do produto", "unit_price" => 100, "quantity" => 1, }, ], "metadata" => { "orderId" => "ORD-123", }, "postbackUrl" => "https://meusite.com.br/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201`: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "pending", "paymentDetails": { "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo..." }, "reason": null, "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q" } ``` Para cobrar com outra forma de pagamento, troque apenas o `paymentMethod`. Os exemplos completos de cada forma estão nos guias específicos e em [Criar uma cobrança](/referencia/cobrancas/criar). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie o endereço com `postalCode`, `addressLine1`, `city`, `state` e `country` | | `400` com `shippingAddress.country must be a valid ISO31661 Alpha3 code` | País em duas letras | Envie `BRA` | | `422` com `Fees not configured` | Conta sem taxa para o método e a moeda | Fale com o suporte da Finvia | | Valor 100 vezes maior | `amount` em centavos | Envie em reais | | `403` ao criar cobrança | Perfil do usuário que gerou a chave | Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave) | | `401` | Chave inválida ou cabeçalho mal montado | Confira [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) | | Não recebe o aviso de chargeback formalizado | Cobrança criada sem `postbackUrl` | Informe `postbackUrl` em todas as cobranças | | Cobrança duplicada após timeout | Reenvio do POST sem verificar a primeira | Siga o [procedimento de timeout](#timeout-na-criação) | ## Perguntas frequentes > [accordion] Preciso cadastrar o cliente antes de cobrar? > > Não. Você pode enviar `name` e `email` (ou `phone`) dentro de `customer` e a API cria ou localiza o cliente na mesma chamada. O `customerId` da resposta traz o cliente usado, quando a cobrança chega ao adquirente. Se você já tem o cliente cadastrado, envie só o `id` dele. Veja [Clientes](/guias/clientes). > [accordion] Posso usar só os webhooks do painel e ignorar a postbackUrl? > > Os endpoints do painel recebem pagamento, recusa síncrona, estorno, bloqueio e pré-chargeback. Dois avisos chegam só pelo `charge.updated`, na `postbackUrl`: o desfecho de cobranças que ficaram em `in_analysis` ou `pending` no cartão e o status `chargeback` do chargeback formalizado (quando o valor é revertido do saldo, os endpoints recebem também `charge.refunded`). Se você não usa `postbackUrl`, consulte essas cobranças periodicamente. > [accordion] A cobrança paga pode mudar de status depois? > > Pode. Uma cobrança `paid` pode ser bloqueada (`isBlocked: true`, ainda `paid`) ou ir para `refunded` (estorno), `pre_chargeback` (alerta de contestação) ou `chargeback`. Mantenha o seu endpoint de webhook ativo e o pedido ligado ao `id` da cobrança. > [accordion] Como acho uma cobrança pelo número do meu pedido? > > Não há filtro por `metadata`. Grave o `id` assim que a criação responder. Se perdeu o `id`, use o `charge.created` ou a listagem com período e `searchFor`, como em [Timeout na criação](#timeout-na-criação). > [accordion] Como sei quais formas de pagamento minha conta aceita? > > Chame [`GET /v1/payment-methods`](/referencia/meios-de-pagamento/listar). O filtro `currency` mostra o que está disponível para uma moeda específica. Pix e Apple Pay aceitam somente `BRL`. ## Como testar Use a chave de teste (`sk_test_`). No Modo Teste, o Pix é confirmado sozinho cerca de 5 segundos depois da criação e o resultado do cartão depende do número usado ([cartões de teste](/guias/cobrancas/cartao-de-credito#cartões-de-teste)). Execute os cenários da seção "Cobrança sem split" do [roteiro de homologação](/homologacao/roteiro): * **CHG-01** e **CHG-02**: cartão aprovado à vista e parcelado. * **CHG-03**: cartão recusado, com `refused` na resposta e o webhook `charge.refused`. * **CHG-04** e **CHG-05**: Pix gerado e Pix pago. * **CHG-06**: consulta da cobrança. * **CHG-07**: estorno total. * **CHG-08** e **CHG-09**: recebimento e simulação de webhook. * **CHG-10**: item físico sem endereço (`400`) e com endereço (`201`). Se você usa split, execute também **SPL-01** a **SPL-06**. ## Veja também > [card] [Pix](/guias/cobrancas/pix) > > QR Code, validade e confirmação por webhook. > [card] [Cartão de crédito](/guias/cobrancas/cartao-de-credito) > > Cartão digitado, parcelamento e recusas. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos e formato dos payloads. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Todos os campos da rota. # Cofre de cartões Source: https://docs.fastpaybrasil.com/guias/cofre-de-cartoes Salve o cartão do cliente com segurança e use o token em compras com um clique e em assinaturas. Esta página trata do **cadastro e da gestão** dos cartões: registrar, conferir o status, listar e excluir. A cobrança com um cartão já guardado (compra com um clique) está em [Cartão salvo](/guias/cobrancas/cartao-salvo). O cofre de cartões guarda o cartão de crédito do cliente de forma segura e devolve um identificador. Com ele, a sua aplicação deixa de manipular o número do cartão nas próximas compras e pode usar o mesmo cartão em uma assinatura. > [!NOTE] > > **Para o negócio:** o cartão salvo permite a compra com um clique, em que o cliente só confirma o código de segurança, e é a base das assinaturas. O seu sistema guarda só o identificador do cartão e os quatro últimos dígitos para exibição; o número completo fica no cofre da Finvia. > [!WARNING] > > **O cadastro de cartão não tem modo de teste.** Mesmo com a chave de teste (`sk_test_`), `POST /v1/cards` registra o cartão de verdade na adquirente. O cadastro não cobra nada: não há transação de validação. O cofre também é o mesmo para teste e produção: um `cardTokenId` criado na homologação funciona com a chave de produção, e aí a mesma chamada de cobrança é real. ## Quando usar | Situação | Como o cofre entra | | - | - | | Recompra com um clique (loja, app, delivery) | Salve o cartão na primeira compra. A cobrança está em [Cartão salvo](/guias/cobrancas/cartao-salvo) | | Assinatura mensal | Registre o cartão e crie a assinatura com `cardTokenId` | | Carteira de cartões na área do cliente | Liste os cartões do cliente com `GET /v1/cards?customerId=...` | | Cliente pede para remover o cartão | Exclua com `DELETE /v1/cards/{id}`, que revoga o token | | Cobrar automaticamente sem o cliente presente, fora de uma assinatura | Não é possível. A cobrança avulsa com cartão salvo exige o CVV a cada vez. Use [Assinaturas](/guias/assinaturas/visao-geral) | ## Como funciona O desenho abaixo mostra o registro do cartão no cofre e os usos do id do cartão salvo. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant A as Seu servidor end box rgb(234,243,255) Finvia participant F as Finvia API participant V as Cofre de cartões end box rgb(244,240,255) Fora da Finvia participant Q as Adquirente end C->>A: Informa os dados do cartão A->>F: POST /v1/cards · customerId · número · validade · CVV F->>V: Guarda o cartão F->>Q: Registra o cartão, sem cobrar nada F-->>A: 201 · id · maskedNumber · status active Note over A: Grave só o id e o maskedNumber. Nunca o número completo nem o CVV opt Compra com um clique C->>A: Digita o CVV A->>F: POST /v1/charges · cardTokenId + cvv end opt Assinatura A->>F: POST /v1/subscriptions · cardTokenId Note over A,F: As cobranças de cada ciclo não pedem CVV end opt Cliente pede para remover A->>F: DELETE /v1/cards/{id} F->>V: Revoga o token end ``` **1. Tenha um cliente cadastrado** O cartão é vinculado a um cliente (`customerId`), que precisa ter e-mail e CPF ou CNPJ. Veja [Clientes](/guias/clientes). **2. Registre o cartão** Envie os dados do cartão para `POST /v1/cards`. O cartão é guardado no cofre, já nasce `active` e a resposta traz o `id` do cartão salvo. **3. Guarde o id e o número mascarado** Grave o `id` e o `maskedNumber` (ex.: `****1111`) no seu sistema. Nunca grave o número completo nem o CVV. **4. Use o cartão** Em uma cobrança, envie o `id` como `cardTokenId`, com o CVV digitado pelo cliente ([Cartão salvo](/guias/cobrancas/cartao-salvo)). Em uma assinatura, envie `cardTokenId`. **5. Remova quando necessário** `DELETE /v1/cards/{id}` revoga o token, que deixa de servir para cobranças e assinaturas. ## Regras de negócio | Regra | Detalhe | | - | - | | Cliente | Precisa de **e-mail** e **CPF ou CNPJ**. O tipo é deduzido pela quantidade de dígitos do documento (11 é CPF, 14 é CNPJ). Sem isso, a resposta é `400` com `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | | Dono do cartão | O cartão pertence ao merchant da chave de API que o registrou. Ele não pode ser usado por outro merchant nem por outra subconta | | Ativação | Não existe etapa de ativação. O cartão nasce `active`, sem transação de teste. O campo `validateCard` é obsoleto e não tem efeito | | CVV na cobrança | Toda cobrança em `POST /v1/charges` com `cardTokenId` exige o `cvv`. Sem ele, a resposta é `400 CVV is required when using cardTokenId`. A recorrência das assinaturas é a única cobrança que dispensa o CVV | | Uso em cobrança | A cobrança recusa cartão `revoked` ou `expired` | | Exclusão | Revoga o token no cofre. O cartão não pode mais ser usado em cobranças nem em assinaturas | | Listagem | `GET /v1/cards` não é paginada e traz no máximo os 20 cartões mais recentes da conta. Filtre por `customerId` | | Modo de teste | O cadastro não tem modo de teste: é real mesmo com a chave de teste, sem cobrar nada. A cobrança com `cardTokenId` em `POST /v1/charges` é simulada com a chave de teste. O cofre é compartilhado entre teste e produção | > [!NOTE] > > O cartão salvo não permite cobrar o cliente ausente fora de uma assinatura: a cobrança avulsa exige o CVV a cada vez. As regras da cobrança estão em [Cartão salvo](/guias/cobrancas/cartao-salvo). ### Status do cartão A listagem e a consulta individual mostram status diferentes, porque cada uma lê uma informação diferente. | Status | Onde aparece | Significado | | - | - | - | | `active` | Listagem e consulta | Cartão ativo | | `expired` | Listagem e consulta | A validade do cartão passou | | `revoked` | Listagem e consulta | Cartão excluído com `DELETE /v1/cards/{id}` | | `inactive` | Só na consulta | A assinatura que usava o cartão foi cancelada e nenhuma outra o usa. Volta a `active` se o cliente assinar de novo com ele | | `pending_validation` | Só na consulta | Aparece só em cartões antigos, registrados com o processador anterior | O desenho abaixo mostra como o status do cartão muda. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB REG(["POST /v1/cards"]):::lojista ACT["active
nasce ativo, sem
transação de teste"]:::ok EXP["expired
validade passou"]:::erro REV["revoked
cartão excluído"]:::erro INA["inactive
só na consulta individual,
nenhuma assinatura o usa"]:::neutro REC["POST /v1/charges
recusa o cartão"]:::erro REG --> ACT ACT -->|"o tempo passa"| EXP ACT -->|"DELETE /v1/cards/{id}"| REV ACT -->|"assinatura
cancelada"| INA INA -->|"assina de
novo"| ACT EXP --> REC REV --> REC classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` `pending_validation` aparece só em cartões antigos, registrados com o processador anterior. > [!WARNING] > > Para saber se um cartão pode ser usado em `POST /v1/charges`, use a listagem (`GET /v1/cards?customerId=...`). Hoje a consulta individual pode mostrar `active` para um cartão já excluído ou vencido. A cobrança recusa cartão `revoked` ou `expired`. ## Passo a passo ### 1. Registrar o cartão ```http REST (JSON) theme={null} POST /v1/cards HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "number": "1111222233334444", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "alias": "Cartão pessoal" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/cards" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "number": "1111222233334444", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "alias": "Cartão pessoal" }' ``` ```javascript Node.js theme={null} // registrar-cartao.mjs (Node.js 18+, ESM) const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/cards', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ customerId: '2vorkDcXyvzifL63YX09S9VqcnI', number: '1111222233334444', holderName: 'JOAO SILVA', expirationMonth: '12', expirationYear: '2028', cvv: '123', }), }); const card = await response.json(); if (!response.ok) { // 400: confira se o cliente tem e-mail e CPF ou CNPJ throw new Error(card.message); } // Guarde card.id (o cardTokenId) e card.maskedNumber no cadastro do cliente console.log('Cartão salvo:', card.id, card.maskedNumber); ``` ```python Python theme={null} import os import requests payload = { "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "number": "1111222233334444", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "alias": "Cartão pessoal", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/cards", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2vorkDcXyvzifL63YX09S9VqcnI', 'number' => '1111222233334444', 'holderName' => 'JOAO SILVA', 'expirationMonth' => '12', 'expirationYear' => '2028', 'cvv' => '123', 'alias' => 'Cartão pessoal', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/cards'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "number": "1111222233334444", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "alias": "Cartão pessoal" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/cards")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "number": "1111222233334444", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "alias": "Cartão pessoal" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/cards"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "number": "1111222233334444", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "alias": "Cartão pessoal" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/cards", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/cards") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "customerId" => "2vorkDcXyvzifL63YX09S9VqcnI", "number" => "1111222233334444", "holderName" => "JOAO SILVA", "expirationMonth" => "12", "expirationYear" => "2028", "cvv" => "123", "alias" => "Cartão pessoal", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` | Campo | Tipo | Obrigatório | Regra | | - | - | - | - | | `customerId` | string | Sim | ID do cliente dono do cartão | | `number` | string | Sim | Número do cartão | | `holderName` | string | Sim | Nome impresso no cartão | | `expirationMonth` | string | Sim | Mês de validade com 2 caracteres (`01` a `12`) | | `expirationYear` | string | Sim | Ano de validade com 4 caracteres (`YYYY`) | | `cvv` | string | Sim | Código de segurança. Mínimo de 3 caracteres | | `alias` | string | Não | Apelido do cartão (ex.: `Cartão pessoal`) | | `validateCard` | boolean | Não | Obsoleto, sem efeito. Não é preciso enviar | Resposta `201`: ```json theme={null} { "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "token": "tok_abc123xyz", "maskedNumber": "****1111", "status": "active", "pendingActivation": false } ``` | Campo | Descrição | | - | - | | `id` | ID do cartão salvo. É o valor usado como `cardTokenId` em cobranças e assinaturas | | `token` | Token do cartão, para referência | | `maskedNumber` | Número mascarado com os 4 últimos dígitos. Pode ser `null` | | `status` | Sempre `active` | | `pendingActivation` | Sempre `false`. Mantido por compatibilidade | > [!TIP] > > **Para o desenvolvedor:** o valor que entra em `cardTokenId` é o campo `id` da resposta. A resposta também traz um campo `token`, que serve só como referência. ### 2. Usar o cartão em uma cobrança Envie o `id` do cartão como `paymentMethod.cardTokenId`, com o CVV digitado pelo cliente. Sem o `cvv`, a resposta é `400 CVV is required when using cardTokenId`. O exemplo completo e as regras da cobrança estão em [Cartão salvo](/guias/cobrancas/cartao-salvo). ### 3. Criar uma assinatura com o cartão salvo ```json theme={null} { "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo" } ``` O cartão precisa pertencer ao mesmo merchant da chave de API. Na assinatura, as cobranças de cada ciclo não pedem CVV. Veja [Assinaturas](/guias/assinaturas/visao-geral). ### 4. Listar os cartões do cliente ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/cards?customerId=2vorkDcXyvzifL63YX09S9VqcnI" \ -u "$FINVIA_API_KEY:" ``` A resposta é um **array**, sem paginação, com no máximo os 20 cartões mais recentes. Com o filtro `customerId`, vêm só os cartões não excluídos (`active` ou `expired`): ```json theme={null} [ { "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "token": "tok_abc123xyz", "maskedNumber": "****1111", "brand": "visa", "expirationMonth": "12", "expirationYear": "2028", "status": "active", "createdAt": "2024-01-15T10:30:00.000Z" } ] ``` Use `brand`, `maskedNumber` e a validade para montar a lista de cartões na área do cliente ("Visa terminado em 1111, validade 12/2028"). ### 5. Consultar um cartão ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/cards/36OO3bcGjhPjjF3tzrqOGcmQuKo" \ -u "$FINVIA_API_KEY:" ``` A resposta tem os mesmos campos da listagem. O `status` segue a tabela de [status do cartão](#status-do-cartão): para decidir se o cartão pode ser cobrado, prefira a listagem. ### 6. Excluir um cartão ```bash cURL theme={null} curl -X DELETE "https://api-global.fastpaybrasil.com/v1/cards/36OO3bcGjhPjjF3tzrqOGcmQuKo" \ -u "$FINVIA_API_KEY:" ``` Resposta `200`: ```json theme={null} { "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "deleted": true, "message": "Card deleted successfully" } ``` > [!WARNING] > > A exclusão revoga o token no cofre. O cartão deixa de servir para cobranças **e para assinaturas**. Se houver uma assinatura usando esse cartão, as próximas renovações não terão como ser cobradas. Antes de excluir, verifique se o cartão está em uso em alguma assinatura ativa. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` `Failed to register card` | Dados do cartão inválidos ou falha no registro | Confira número, validade (`MM` e `YYYY`) e CVV | | `400` `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 nem 14 dígitos | Use um cliente com e-mail e CPF ou CNPJ | | `400` `CVV is required when using cardTokenId` | Cobrança com cartão salvo sem o `cvv` | Peça o CVV ao cliente e envie em `paymentMethod.cvv` | | Cobrança recusada com cartão que a consulta mostra `active` | Cartão excluído ou vencido. A consulta individual pode mostrar `active` nesse caso | Confira o cartão na listagem com `customerId` | | Cartão não encontrado ao usar em subconta | O cartão pertence ao merchant que o registrou | Registre o cartão com a chave da conta que vai cobrar | | `404` `Card not found` | `id` errado ou cartão de outro merchant | Confira o `id` (não o `token`) | | Assinatura deixou de renovar | Cartão excluído ou vencido | Cancele a assinatura e crie outra com um cartão válido | ## Perguntas frequentes > [accordion] O cliente precisa confirmar algum valor na fatura para ativar o cartão? > > Não. O cartão nasce `active`, sem transação de teste e sem etapa de ativação. > [accordion] Posso testar o cofre no sandbox? > > Em parte. O cadastro (`POST /v1/cards`) não tem modo de teste: com a chave de teste, o cartão é registrado de verdade, sem cobrar nada. Já a cobrança com `cardTokenId` em `POST /v1/charges` é simulada com a chave de teste e não movimenta dinheiro; o resultado segue as regras dos [cartões de teste](/primeiros-passos/credenciais-e-ambientes#cartões-de-teste) aplicadas ao número guardado. As assinaturas não têm modo de teste: as cobranças delas são reais. Use um cartão real para homologar e lembre que o mesmo `cardTokenId` funciona com a chave de produção. > [accordion] Um cartão salvo pela conta master pode ser usado por uma subconta? > > Não. O cartão pertence ao merchant da chave de API que o registrou e não pode ser usado por outro merchant ou subconta. > [accordion] Como troco o cartão de uma assinatura? > > A assinatura não permite troca de cartão. Registre o novo cartão, cancele a assinatura atual e crie outra com o novo `cardTokenId`. A nova assinatura começa um ciclo novo, com cobrança imediata. ## Como testar | Código | Cenário | O que comprovar | | - | - | - | | SUB-01 | Registrar cartão com cliente com e-mail e CPF ou CNPJ | `status: "active"` e `pendingActivation: false` (sem o número do cartão na evidência) | | SUB-02 | Cobrança com um clique, descrita em [Cartão salvo](/guias/cobrancas/cartao-salvo) | Status `paid` e coleta do CVV a cada cobrança. Com a chave de teste, a cobrança é simulada | | SUB-04 | Assinatura com `cardTokenId` | Status `active` e primeira cobrança processada. A cobrança é real, mesmo com a chave de teste: cancele em até 7 dias para que as cobranças pagas sejam estornadas | ## Veja também > [card] [Cartão salvo](/guias/cobrancas/cartao-salvo) > > Cobrança com um clique usando o cartão guardado. > [card] [Clientes](/guias/clientes) > > Cadastro do cliente dono do cartão. > [card] [Assinaturas](/guias/assinaturas/visao-geral) > > Cobrança recorrente com cartão salvo. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Contrato completo da rota. # Estorno Source: https://docs.fastpaybrasil.com/guias/estorno Devolva ao cliente o valor de uma cobrança paga, por Pix ou cartão: regras, prazos, efeito no saldo, split e estorno depois do saque. O estorno devolve ao cliente o valor de uma cobrança paga. Você pede o estorno com uma única chamada, `POST /v1/refunds`, informando a cobrança e o motivo. O estorno vale para cobranças Pix e de cartão de crédito (inclusive cartão salvo e Apple Pay) e é sempre do valor total da cobrança. > [!NOTE] > > **Para o negócio:** use o estorno quando o pedido é cancelado, o produto não pode ser entregue ou o cliente desiste da compra. O cliente recebe o valor integral pelo mesmo meio de pagamento, a cobrança passa a `refunded` e os sistemas conectados recebem o aviso `charge.refunded`. Do seu saldo sai o valor bruto da venda: as taxas da venda não são devolvidas. > [!WARNING] > > O estorno é feito **somente pela API**. A Finvia não faz estorno por chamado ou pelo suporte, exceto em caso de erro sistêmico. Se a sua equipe de atendimento precisa estornar, dê a ela uma tela no seu sistema que chame `POST /v1/refunds`. ## Quando usar | Situação | Use estorno? | | - | - | | Pedido cancelado antes da entrega | Sim | | Cliente desistiu da compra e você aceitou devolver | Sim | | Cobrança feita em duplicidade | Sim, estorne a cobrança duplicada | | Cliente quer devolver só um item de um pedido com vários | O estorno é sempre do valor total da cobrança | | Cobrança ainda `pending` (Pix não pago) | Não: só cobranças `paid` podem ser estornadas | | Cliente contestou no banco (chargeback) ou abriu MED | Siga o fluxo de [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) | | Assinatura cancelada em até 7 dias | O cancelamento da assinatura já estorna as cobranças pagas ([Ciclo de vida](/guias/assinaturas/ciclo-de-vida)) | ## Como funciona O desenho abaixo mostra o caminho de um pedido de estorno, da consulta da cobrança ao aviso por webhook. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant S as Seu servidor end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant E as Pix ou adquirente end S->>F: GET /v1/charges/{id} F-->>S: status paid, sem estorno anterior S->>F: POST /v1/refunds · chargeId · reason alt Cobrança paid, Pix ou cartão F->>E: Pix: devolução do pagamento original
Cartão: pedido de estorno à adquirente F-->>S: 201 · status refunded · pspRefundRefId Note over S,F: O valor sai do seu saldo na hora E-->>C: Pix: costuma chegar em segundos
Cartão: crédito na fatura, no prazo do emissor F-)S: charge.refunded nos endpoints e na postbackUrl else Não está paid ou já tem estorno F-->>S: 404 Cobrança não encontrada · 422 já existe reembolso else Método ou provedor sem estorno F-->>S: 501 end Note over F,E: Se a adquirente ou o banco não concluir sozinho, a resposta continua refunded e a equipe Finvia conclui o estorno ``` **1. Confira a cobrança** A cobrança precisa estar `paid` e não pode ter outro estorno. Consulte com `GET /v1/charges/{id}`. **2. Peça o estorno** Seu servidor chama `POST /v1/refunds` com `chargeId` e `reason`, usando a chave secreta da conta dona da cobrança. **3. Leia a resposta** A resposta `201` traz `status` `refunded`: o estorno foi registrado na Finvia e o valor saiu do seu saldo. **4. A Finvia devolve ao comprador** No Pix, sai uma devolução do pagamento original na hora. No cartão, o pedido vai à adquirente na hora e o crédito aparece na fatura do comprador conforme o prazo do banco emissor. **5. Os webhooks avisam** A cobrança passa a `refunded` e o evento `charge.refunded` é enviado aos endpoints de webhook cadastrados e à `postbackUrl` da cobrança, se ela foi informada. ## Regras de negócio | Regra | Detalhe | | - | - | | Valor | Sempre o valor total da cobrança. Não há estorno parcial | | Status da cobrança | Precisa estar `paid`. Cobrança pendente, já estornada, em `pre_chargeback` ou em `chargeback` recebe `404` `Cobrança não encontrada` | | Cobrança bloqueada | Continua `paid` e pode ser estornada. O débito sai do saldo bloqueado | | Quantidade | Um estorno por cobrança. O segundo pedido recebe `422` `Já existe um reembolso para esta cobrança` | | Formas de pagamento | Pix e cartão de crédito. Outros métodos ou provedores sem estorno recebem `501` | | Prazo para pedir | A API não impõe prazo máximo. No Pix, peça em até 90 dias do pagamento (regra do Pix) | | Quem pede | A conta dona da cobrança. Em venda com split, o recebedor não consegue estornar | | Motivo | `reason` é obrigatório, em texto livre, e fica registrado para auditoria | | Canal | Só pela API (`POST /v1/refunds`). Sem estorno por chamado, exceto em erro sistêmico | | Notificação | `charge.refunded` para os endpoints cadastrados e para a `postbackUrl` | ## Prazo para o comprador receber O prazo depende do meio de pagamento, e não da API. | Meio | Como a devolução acontece | Prazo para o comprador | | - | - | - | | Pix | Devolução Pix do pagamento original, enviada na hora | Quando aceita, o dinheiro costuma chegar em segundos na conta de origem. Pelas regras do Pix, a devolução precisa ser pedida em até 90 dias do pagamento; depois disso, o banco pode recusar | | Cartão de crédito | O pedido vai à adquirente na hora | O crédito aparece na fatura do comprador conforme o prazo do banco emissor: pode levar até duas faturas, conforme a data de fechamento | > [!NOTE] > > A resposta `refunded` significa que o estorno foi registrado na Finvia e o valor saiu do seu saldo. Se a adquirente ou o banco não concluir o estorno automaticamente, a API responde `refunded` mesmo assim e a equipe Finvia conclui o estorno manualmente. Nesse caso o comprador pode demorar mais para receber. Não reenvie o pedido: se o comprador não receber, acione o suporte com o `chargeId`. ## Quanto sai do seu saldo | Situação da venda | O que acontece | | - | - | | Venda já liquidada | O comprador recebe o valor integral. Do seu saldo disponível sai o valor bruto da venda: o líquido já liquidado mais as taxas. As taxas da venda não são devolvidas | | Venda ainda não liquidada (ex.: parcelas futuras de cartão) | Os recebíveis futuros da venda são cancelados e só o valor das taxas sai do saldo disponível | | Cobrança bloqueada (MED ou chargeback em análise) | O débito sai do saldo bloqueado | **Exemplo:** uma venda de R\$ 100,00 no Pix, com R\$ 1,00 de taxa, já liquidada. Você recebeu R\$ 99,00 no saldo disponível. No estorno, o comprador recebe R\$ 100,00 e sai R\$ 100,00 do seu saldo disponível (os R\$ 99,00 recebidos mais a taxa de R\$ 1,00, que não volta). ## Estorno de venda com split * O estorno é sempre da cobrança inteira. Não dá para estornar só a parte de um recebedor. * O pedido é feito pela conta dona da cobrança (o originador). O recebedor do split não consegue estornar a venda. * **Partes do split já repassadas:** cada recebedor devolve o que recebeu. O valor é debitado do saldo disponível dele (ou do bloqueado, se a conta estiver retida) e volta ao originador antes do débito total. * **Partes ainda não repassadas:** são canceladas e ninguém recebe. ## Estorno depois do saque O estorno é permitido mesmo que o valor da venda já tenha sido sacado. A API não confere o saldo antes de estornar: * Se o valor já saiu da conta, o saldo disponível fica **negativo**. O mesmo vale para o recebedor do split. * O negativo é compensado pelas próximas liquidações. * Novos saques só passam quando o saldo disponível cobre o valor pedido. Antes disso, a API responde `422` `Insufficient balance`. O desenho abaixo resume o efeito do estorno no split e no seu saldo, inclusive quando o valor já foi sacado. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB EST(["Estorno registrado
cobrança refunded"]):::neutro CLI(["Comprador recebe
o valor integral"]):::comprador SPL{"Tem split?"}:::decisao REP["Partes já repassadas:
cada recebedor devolve
o que recebeu"]:::alerta NREP["Partes não repassadas:
canceladas,
ninguém recebe"]:::neutro SIT{"Situação
da venda?"}:::decisao LIQ["Já liquidada
sai o valor bruto do
saldo disponível"]:::alerta NLIQ["Ainda não liquidada
recebíveis futuros cancelados,
sai só o valor das taxas"]:::alerta BLQ["Cobrança bloqueada
o débito sai do
saldo bloqueado"]:::alerta COB{"O disponível
cobre?"}:::decisao OK(["Débito concluído"]):::ok NEG["Saldo disponível
fica negativo"]:::erro COMP["Próximas liquidações
compensam o negativo"]:::neutro SAQ["Novos saques recebem
422 Insufficient balance
até o saldo cobrir"]:::erro EST -->|"devolução"| CLI EST --> SPL SPL -->|"sim"| REP SPL -->|"sim"| NREP REP -->|"volta ao originador
antes do débito total"| SIT SPL -->|"não"| SIT SIT --> LIQ SIT --> NLIQ SIT --> BLQ LIQ --> COB NLIQ --> COB COB -->|"sim"| OK COB -->|"não, já sacado"| NEG NEG --> COMP NEG -.-> SAQ classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` O saldo negativo vale também para o recebedor do split que já sacou a parte dele. **Em validação (V-59):** o time de produto ainda confirma o texto do prazo do cartão ("até duas faturas"), a regra das taxas e do saldo negativo e a resposta `refunded` quando a adquirente recusa. ## Passo a passo ### 1. Peça o estorno ```http REST (JSON) theme={null} POST /v1/refunds HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/refunds" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/refunds', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ chargeId: '2vorkDcXyvzifL63YX09S9VqcnI', reason: 'Pedido ORD-123 cancelado pelo cliente', }), }); const refund = await response.json(); console.log(response.status, refund); ``` ```python Python theme={null} import os import requests payload = { "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/refunds", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2vorkDcXyvzifL63YX09S9VqcnI', 'reason' => 'Pedido ORD-123 cancelado pelo cliente', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/refunds'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/refunds")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/refunds"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/refunds", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/refunds") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "chargeId" => "2vorkDcXyvzifL63YX09S9VqcnI", "reason" => "Pedido ORD-123 cancelado pelo cliente", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201 Created`: ```json theme={null} { "status": "refunded", "reason": null, "pspRefundRefId": "psp_refund_abc123xyz" } ``` | Campo | Tipo | Descrição | | - | - | - | | `status` | string | Hoje sempre `refunded` | | `reason` | string ou `null` | Texto informado pelo provedor de pagamento. Pode vir preenchido mesmo em sucesso: decida pelo `status` | | `pspRefundRefId` | string ou `null` | ID de referência do estorno no provedor, quando disponível | > [!TIP] > > **Para o desenvolvedor:** guarde o `pspRefundRefId` junto com o pedido. Ele é a referência do estorno no processador e ajuda no atendimento ao cliente e na conciliação. ### 2. Trate o webhook charge.refunded Quando o estorno é registrado, os endpoints e a `postbackUrl` recebem o evento no envelope padrão: ```json theme={null} { "id": "2xKr8Sn5UaX0cO4qM9dW2eZ7iKf", "event": "charge.refunded", "livemode": true, "data": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "refunded", "amount": 100, "currency": "BRL", "net": 99, "payment_method": { "type": "pix" }, "metadata": { "orderId": "ORD-123" }, "paid_at": "2026-10-20T10:35:00.000Z", "updated_at": "2026-10-27T11:00:00.000Z" } } ``` O exemplo mostra parte do objeto `data`. O payload completo está em [Webhooks de cobrança](/guias/webhooks/cobranca). Quando o estorno é feito no tratamento de um alerta de pré-chargeback, o payload traz `chargeback_alert_refunded: true`. ```javascript Node.js theme={null} // webhook-estorno.mjs (Node.js 18+, ESM, com express instalado) import express from 'express'; const app = express(); app.use(express.json()); // Troque pelo seu banco de dados. O Set em memória serve só para o exemplo. const eventosProcessados = new Set(); async function marcarPedidoComoEstornado(chargeId) { // Revogue o acesso ou cancele a entrega e registre o estorno no pedido console.log('Pedido estornado:', chargeId); } app.post('/webhooks/finvia', async (req, res) => { const { id, event, data } = req.body; res.status(200).send('OK'); if (!id || eventosProcessados.has(id)) return; if (event === 'charge.refunded') { await marcarPedidoComoEstornado(data.id); } eventosProcessados.add(id); }); app.listen(3000); ``` ### 3. Estorno com proteção contra duplicidade Cada cobrança comporta um único estorno, e a API recusa o segundo pedido com `422`. A rotina abaixo grava o resultado e trata as respostas de erro como finais. ```javascript Node.js theme={null} // estorno-seguro.mjs (Node.js 18+, ESM) const API_URL = 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); // Troque pelo seu banco de dados. O Map em memória serve só para o exemplo. const estornos = new Map(); async function estornarComSeguranca(chargeId, motivo) { // 1. Já existe estorno registrado para esta cobrança no seu sistema? if (estornos.has(chargeId)) return { ...estornos.get(chargeId), repetido: true }; // 2. Peça o estorno const response = await fetch(`${API_URL}/v1/refunds`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ chargeId, reason: motivo }), }); const body = await response.json(); // 3. 422: a cobrança já tinha um estorno. Trate como concluído, sem repetir. if (response.status === 422) { const registro = { status: 'refunded', origem: 'estorno anterior' }; estornos.set(chargeId, registro); return registro; } // 4. 404 (cobrança não paga ou inexistente), 501 (método sem estorno) e outros erros if (!response.ok) { return { erro: true, httpStatus: response.status, message: body.message }; } // 5. Grave o resultado antes de qualquer outra ação const registro = { status: body.status, pspRefundRefId: body.pspRefundRefId }; estornos.set(chargeId, registro); return registro; } const resultado = await estornarComSeguranca('2vorkDcXyvzifL63YX09S9VqcnI', 'Pedido cancelado pelo cliente'); console.log(resultado); ``` Depois de um timeout no pedido de estorno, consulte a cobrança com `GET /v1/charges/{id}` antes de repetir. Se ela estiver `refunded`, grave o resultado e não peça de novo. ## Erros comuns | HTTP | `message` | Causa | Como resolver | | - | - | - | - | | `401` | `Unauthorized` | Chave inválida ou cabeçalho mal montado | Confira [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) | | `403` | `Acesso negado` | O perfil do usuário que gerou a chave não tem permissão | Gere a chave com um usuário Owner ou Manager | | `404` | `Cobrança não encontrada` | `chargeId` inexistente, de outro ambiente ou cobrança que não está `paid` (pendente, já estornada, `pre_chargeback`, `chargeback`) | Consulte a cobrança. Só cobranças `paid` podem ser estornadas | | `422` | `Já existe um reembolso para esta cobrança` | A cobrança já tem um estorno | Não envie outro pedido | | `501` | `Reembolso não implementado para este método de pagamento` ou `Reembolso não disponível para este provedor de pagamento` | Método ou provedor sem estorno pela API | Só Pix e cartão têm estorno | | `500` | | Falha na Finvia | Consulte a cobrança antes de tentar de novo | Os erros seguem o formato padrão (`statusCode`, `message`, `error`). Trate pelo código HTTP: as mensagens podem mudar. ## Perguntas frequentes > [accordion] Posso devolver só parte do valor? > > Não. O estorno é sempre do valor total da cobrança. A API não recebe um valor no pedido de estorno. > [accordion] Posso pedir o estorno ao suporte da Finvia? > > Não. O estorno é feito só pela rota `POST /v1/refunds`. A Finvia só atua diretamente em caso de erro sistêmico. > [accordion] O comprador diz que não recebeu. O que faço? > > No Pix, a devolução costuma chegar em segundos. No cartão, o crédito depende do fechamento da fatura do emissor. Se o prazo passou, acione o suporte com o `chargeId`: pode ser um caso em que a adquirente não concluiu o estorno automaticamente e a equipe Finvia está concluindo. Não peça outro estorno. > [accordion] As taxas da venda voltam para mim? > > Não. Do seu saldo sai o valor bruto da venda, e as taxas cobradas na venda não são devolvidas. > [accordion] Já saquei o dinheiro da venda. Posso estornar? > > Pode. O saldo disponível fica negativo e é compensado pelas próximas liquidações. Enquanto isso, novos saques recebem `422` `Insufficient balance`. > [accordion] Estorno e chargeback são a mesma coisa? > > São processos diferentes. O estorno é pedido por você. O chargeback é uma contestação que o titular do cartão abre no banco emissor. Veja [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ## Como testar No [roteiro de homologação](/homologacao/roteiro): * **CHG-07:** estorno total de uma cobrança paga, com status `refunded` e webhook `charge.refunded`. No Modo Teste, crie um Pix com a chave `sk_test_`: ele vira `paid` sozinho em cerca de 5 segundos e já pode ser estornado. * **AP-05:** estorno de uma cobrança Apple Pay paga, se você usa Apple Pay. Para testar só o tratamento do evento, use [`POST /v1/charges/{id}/resend-webhook`](/referencia/cobrancas/reenviar-webhook-teste) com `{"status": "refunded"}`. Ele dispara um evento simulado e não altera a cobrança. ## Veja também > [card] [Estornar cobrança](/referencia/cobrancas/estornar) > > Referência de `POST /v1/refunds`. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Payload do `charge.refunded`. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > Contestações abertas pelo cliente. > [card] [Split](/guias/fast-connect/split) > > Como o repasse funciona antes do estorno. # Cálculo de split Source: https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split Como calcular o percentual de split a informar à Finvia quando a sua plataforma cobra uma taxa própria sobre o valor bruto da venda. Quando uma plataforma integrada ao Connect (conta master e subcontas) cobra uma taxa própria sobre as vendas das subcontas e recebe essa taxa por split, aparece uma diferença de base de cálculo. Por padrão, a Finvia aplica o split sobre o [valor líquido](/glossario), depois de descontar a taxa transacional da venda. A plataforma, em geral, define a comissão sobre o [valor bruto](/glossario). Por isso o percentual de split precisa ser ajustado para chegar ao valor combinado. > [!NOTE] > > **Para o negócio:** se o contrato com o vendedor diz "2% sobre o valor da venda", o percentual enviado no split fica um pouco acima de 2%. A diferença existe porque o split incide sobre um valor menor (o líquido). O objetivo é que o vendedor pague os 2% combinados sobre o bruto. Se o vendedor antecipar os recebíveis, a base do split diminui e a comissão recebida fica menor que o alvo (veja [Cuidados](#cuidados)). ## Quando usar * A sua plataforma cobra uma comissão percentual sobre o valor bruto de cada venda das subcontas. * Você quer que a comissão recebida por split fique alinhada ao valor do contrato. * Você mostra ao vendedor um extrato com "valor da venda, taxa da plataforma e valor a receber". Se a sua comissão já é definida sobre o valor líquido (depois das taxas da Finvia), envie o percentual direto, sem ajuste. ## O problema Com a base líquida, que é o padrão, o split é calculado **depois** da dedução da taxa transacional da Finvia sobre a cobrança: * taxa percentual transacional, que depende do método, da bandeira e do número de parcelas; * taxa fixa por transação (por exemplo, R\$ 0,40). O que sobra é o **valor líquido**, e é sobre ele que o percentual de split é aplicado. A plataforma calcula a taxa dela sobre o **valor bruto** da venda. Se você usar o mesmo percentual nos dois lados, a plataforma recebe menos, porque a base do split (líquido) é menor que a base da cobrança (bruto). Exemplo rápido: venda de R\$ 100,00 com R\$ 5,40 de taxa transacional. Com `percentage: 2`, a plataforma recebe 2% de R\$ 94,60, ou seja, R\$ 1,89. O combinado eram R\$ 2,00. > [!NOTE] > > A taxa de antecipação **só reduz a base** do split quando o originador antecipa o recebível. Sem antecipação, o repasse é o percentual sobre o valor líquido da taxa transacional. Calcular o split sobre o valor bruto é uma configuração de conta feita pela Finvia, sob consulta; com ela, nenhum ajuste desta página é necessário. ## De onde vêm as taxas As taxas que entram no cálculo (`f` e `c`) não devem ficar fixas no código. Elas são da própria subconta e podem variar por método de pagamento, moeda, bandeira e número de parcelas. Consulte direto na API: ```bash theme={null} GET /v1/fast-connect/sub-accounts/{id}/fees-info ``` A rota devolve as taxas efetivas da subconta: na cobrança, a API usa só as taxas da própria conta que cobra. Os detalhes estão em [Taxas da subconta](/guias/fast-connect/taxas). A resposta traz `fees` como uma **lista plana**. Para chegar à taxa transacional efetiva: **1. Filtre a linha transacional** `feeType` `tx_spread`, com `paymentMethod` e `currencyCode` iguais aos da cobrança. **2. Escolha a bandeira** No cartão, use a linha com `brand` igual à bandeira do cartão. Se ela não existir, use a linha com `brand: null`. **3. Leia o percentual e a taxa fixa** O percentual é `definition.percentages[parcelas - 1]` (índice `0` = à vista). A taxa fixa é `definition.fixed`, por transação. | Campo da API | Uso no cálculo | | - | - | | `feeType: "tx_spread"` | Taxa **transacional**. Entra em `f` e `c` | | `feeType: "anticipation"` | Taxa de **antecipação**, mensal. Não entra em `f`: só pesa quando o originador antecipa (veja [Cuidados](#cuidados)) | | `definition.percentages[n - 1]` | Percentual transacional para `n` parcelas | | `definition.fixed` | Taxa **fixa** por transação. Entra em `c` | | `paymentMethod`, `currencyCode`, `brand` | Filtros para escolher a linha de taxa correta | > [!WARNING] > > Se `fees` vier vazio, ou sem linha para o método e a moeda da venda, a subconta não tem taxa configurada para essa combinação, e as cobranças dela são recusadas com `422` `Fees not configured`. Não calcule com taxa zero nem com as taxas da master: fale com o suporte da Finvia. ## A fórmula Para que o split entregue o valor que a plataforma quer cobrar sobre o bruto: ```text theme={null} L = V × (1 − f) − c s = (p × V) ÷ L ``` | Variável | Significado | | - | - | | `V` | Valor bruto da venda | | `f` | Taxa percentual transacional da Finvia, em fração (ex.: `0,05` para 5%) | | `c` | Taxa fixa da Finvia por transação, em reais (ex.: `0,40`) | | `L` | Valor líquido depois da taxa transacional | | `p` | Taxa que a plataforma quer cobrar sobre o bruto, em fração (ex.: `0,02` para 2%) | | `s` | Percentual de split a informar à Finvia, aplicado sobre `L` (multiplique por 100 para enviar em `percentage`) | ## Exemplo passo a passo Venda de **R\$ 100,00** em 2x, com taxa transacional de 5% para 2x e taxa fixa de R\$ 0,40. A plataforma quer cobrar **2% sobre o bruto**. O desenho abaixo mostra a cascata deste exemplo: do valor bruto ao líquido, do líquido ao percentual de split, e quanto fica com cada um. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB V["Venda em 2x
valor bruto V = R$ 100,00"]:::neutro A95["Depois da taxa percentual
R$ 95,00"]:::neutro L["Valor líquido L
R$ 94,60"]:::alerta ALVO["Alvo da plataforma
2% de R$ 100,00 = R$ 2,00"]:::neutro S["Seu servidor calcula
s = 2,00 ÷ 94,60 = 2,1142%
percentage: 2.1142"]:::lojista FINV(["Finvia, taxa transacional
5,00 + 0,40 = R$ 5,40"]):::finvia PLAT(["Plataforma, conta master
2,1142% de 94,60 = R$ 2,00"]):::ok VEND(["Vendedor, subconta
94,60 − 2,00 = R$ 92,60"]):::ok V -->|"1. taxa de 5% (f = 0,05)
menos R$ 5,00"| A95 A95 -->|"2. taxa fixa (c)
menos R$ 0,40"| L V -.->|"comissão p = 0,02
sobre o bruto"| ALVO L -->|"3. base do split"| S ALVO -->|"3. valor desejado"| S S ==>|"4. split"| PLAT S ==>|"4. o que sobra"| VEND S ~~~ FINV classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Conferência: R\$ 5,40 da Finvia + R\$ 2,00 da plataforma + R\$ 92,60 do vendedor somam os R\$ 100,00 da venda, quando não há antecipação. **1. Leia a taxa transacional** Na linha `tx_spread` da bandeira, `percentages[1]` = 5, então `f = 0,05`. A taxa fixa é `c = 0,40`. **2. Calcule o valor líquido** `L = 100 × (1 − 0,05) − 0,40 = 95 − 0,40 =` **R\$ 94,60**. **3. Defina o valor que a plataforma quer receber** 2% sobre o bruto: `0,02 × 100 =` **R\$ 2,00**. **4. Calcule o percentual de split** `s = 2,00 ÷ 94,60 =` **2,1142%**. Na cobrança, envie `"percentage": 2.1142`. **5. Confira** `2,1142% × 94,60 =` **R\$ 2,00**. O vendedor (subconta) fica com `94,60 − 2,00 =` **R\$ 92,60**, que é o mesmo que `100 − 5 − 0,40 − 2`. > [!TIP] > > A conta fecha quando a soma "taxa transacional da Finvia + valor da plataforma + valor do vendedor" é igual ao valor bruto. No exemplo: R\$ 5,40 + R\$ 2,00 + R\$ 92,60 = R\$ 100,00. Isso vale quando o vendedor não antecipa. ## Tabela de referência A tabela abaixo funciona como uma calculadora pronta para conferência, sem antecipação. O primeiro caso é o exemplo acima. Os outros três usam taxas ilustrativas. Na sua integração, use sempre as taxas reais da subconta. | Caso | Valor bruto (`V`) | Taxa transacional (`f`) | Taxa fixa (`c`) | Comissão sobre o bruto (`p`) | Líquido (`L`) | Plataforma recebe | Split a informar (`s`) | Finvia recebe | Vendedor recebe | | - | - | - | - | - | - | - | - | - | - | | Cartão 2x (exemplo acima) | R\$ 100,00 | 5% | R\$ 0,40 | 2% | R\$ 94,60 | R\$ 2,00 | 2,1142% | R\$ 5,40 | R\$ 92,60 | | Pix à vista, taxa só percentual | R\$ 200,00 | 1,5% | R\$ 0,00 | 3% | R\$ 197,00 | R\$ 6,00 | 3,0457% | R\$ 3,00 | R\$ 191,00 | | Cartão Visa 6x | R\$ 600,00 | 5,49% | R\$ 0,50 | 2% | R\$ 566,56 | R\$ 12,00 | 2,1180% | R\$ 33,44 | R\$ 554,56 | | Cartão Visa à vista, comissão de 5% | R\$ 300,00 | 2,99% | R\$ 0,50 | 5% | R\$ 290,53 | R\$ 15,00 | 5,1630% | R\$ 9,47 | R\$ 275,53 | Como cada linha foi calculada: * **Pix à vista**: `L = 200 × (1 − 0,015) − 0 = 197,00`. `s = 6,00 ÷ 197,00 = 3,0457%`. Conferência: R\$ 3,00 + R\$ 6,00 + R\$ 191,00 = R\$ 200,00. * **Cartão Visa 6x**: na linha `tx_spread` da bandeira Visa, `percentages[5]` = 5,49. `f = 0,0549`. `L = 600 × 0,9451 − 0,50 = 566,56`. `s = 12,00 ÷ 566,56 = 2,1180%`. Conferência: R\$ 33,44 + R\$ 12,00 + R\$ 554,56 = R\$ 600,00. * **Cartão Visa à vista com 5%**: `percentages[0]` = 2,99. `L = 300 × 0,9701 − 0,50 = 290,53`. `s = 15,00 ÷ 290,53 = 5,1630%`. Conferência: R\$ 9,47 + R\$ 15,00 + R\$ 275,53 = R\$ 300,00. Os percentuais de split estão arredondados para 4 casas decimais. As taxas da tabela são ilustrativas. ## Implementação A conversão em código recebe as taxas em fração e devolve o percentual de split: ```ts TypeScript theme={null} interface ParametrosSplit { valorBruto: number; // ex.: 100 taxaPercentualFinvia: number; // ex.: 0.05 (taxa transacional para o número de parcelas) taxaFixaFinvia: number; // ex.: 0.40 taxaClienteSobreBruto: number; // ex.: 0.02 } function calcularSplit(p: ParametrosSplit): number { const liquido = p.valorBruto * (1 - p.taxaPercentualFinvia) - p.taxaFixaFinvia; if (liquido <= 0) { throw new Error("Valor líquido não positivo: taxas excedem o valor da venda."); } const valorDesejado = p.valorBruto * p.taxaClienteSobreBruto; const splitPercentual = (valorDesejado / liquido) * 100; return splitPercentual; // ex.: 2.1142 (informar à Finvia) } ``` E para obter `f` e `c` a partir da resposta de `fees-info`, escolhendo a linha transacional certa por método, moeda e bandeira e a parcela desejada: ```ts TypeScript theme={null} interface FeeItem { feeType: "tx_spread" | "anticipation"; paymentMethod: string | null; currencyCode: string | null; brand: string | null; definition: { fixed: number; percentages: number[] }; } interface Filtro { paymentMethod: string; // ex.: "credit_card" currencyCode: string; // ex.: "BRL" brand: string | null; // ex.: "visa"; null no Pix parcelas: number; // ex.: 2; 1 no Pix } function obterTaxasFinvia(fees: FeeItem[], filtro: Filtro) { const candidatas = fees.filter( (i) => i.feeType === "tx_spread" && i.paymentMethod === filtro.paymentMethod && i.currencyCode === filtro.currencyCode, ); // a linha da bandeira tem prioridade; cai em brand: null quando não houver const linha = candidatas.find((i) => i.brand === filtro.brand) ?? candidatas.find((i) => i.brand === null); if (!linha) { // sem taxa para a combinação: a cobrança seria recusada com 422 Fees not configured throw new Error("Taxa não configurada para este método e moeda. Fale com o suporte da Finvia."); } const percentual = linha.definition.percentages[filtro.parcelas - 1]; if (percentual === undefined) { throw new Error(`Sem taxa para ${filtro.parcelas} parcelas.`); } return { taxaPercentualFinvia: percentual / 100, // f taxaFixaFinvia: linha.definition.fixed, // c }; } ``` Juntando as duas funções no seu servidor, antes de criar a cobrança. Este bloco continua os dois anteriores e usa a função `consultarFeesInfo` de [Taxas da subconta](/guias/fast-connect/taxas): ```ts TypeScript theme={null} const { fees } = await consultarFeesInfo(subcontaId); // GET /v1/fast-connect/sub-accounts/{id}/fees-info const taxas = obterTaxasFinvia(fees, { paymentMethod: "credit_card", currencyCode: "BRL", brand: "visa", parcelas: 6, }); const percentage = calcularSplit({ valorBruto: 600, ...taxas, taxaClienteSobreBruto: 0.02, }); // Com as taxas do caso "Cartão Visa 6x" da tabela: percentage ≈ 2.1180 ``` ## Cuidados > [!WARNING] > > **Antecipação pelo originador:** só o originador (normalmente a subconta do vendedor) antecipa o recebível. Quando ele antecipa, de forma manual ou automática, o split é recalculado sobre o valor já descontada a taxa de antecipação, e a plataforma passa a receber proporcionalmente menos que o valor alvo. A taxa de antecipação de `fees-info` é **mensal**: só `percentages[0]` é usado, multiplicado pelo número de meses até o vencimento de cada parcela (mínimo de 1 mês). Por isso o efeito é maior em vendas com mais parcelas. A opção de a conta master absorver a taxa de antecipação das subcontas existe sob consulta. Enquanto a cobrança não liquida, o `splitAmount` de `GET /v1/charges/{id}` mostra uma simulação do valor com antecipação, menor que o valor da tabela. Depois que as parcelas liquidam sem antecipação, ele passa a mostrar o percentual sobre o valor líquido. Veja [Split de pagamentos](/guias/fast-connect/split). Na conciliação, compare o valor que a plataforma recebeu com o valor alvo (`p × V`). A diferença mostra quanto a antecipação ou uma mudança de taxa afastou o resultado do cálculo. > [!NOTE] > > O percentual de split carrega arredondamento (ex.: `2,1142%`). Mantenha as casas decimais do percentual e arredonde para 2 casas só o **valor resultante em reais**, no fechamento, para evitar diferenças de centavos em valores altos. No caso "Cartão Visa 6x", por exemplo, arredondar o percentual para 2,12% daria `2,12% × 566,56 = R$ 12,01`, um centavo a mais que os R\$ 12,00 combinados. Com 2,1180%, o resultado é R\$ 12,00. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Comissão recebida menor que a combinada | Percentual da comissão enviado sem ajuste | Calcule `s` com a fórmula desta página | | Comissão errada só em algumas bandeiras | Linha `brand: null` usada quando havia linha da bandeira, ou o contrário | Use a linha da bandeira quando existir e `brand: null` só na ausência dela | | Comissão errada em vendas parceladas | Índice da parcela deslocado (uso de `percentages[n]` para `n` parcelas) | O índice `0` é à vista. Para 6x, use o índice `5` | | Comissão menor que a calculada em vendas antecipadas | O originador antecipou e a base do split foi reduzida pela taxa de antecipação | Comportamento esperado com base líquida. Fale com a Finvia sobre as opções sob consulta | | Taxa de antecipação somada em `f` | A antecipação só reduz a base quando o originador antecipa | Use só a linha `tx_spread` no cálculo | | Diferença de centavos em valores altos | Percentual arredondado para poucas casas | Mantenha mais casas no percentual e arredonde o valor em reais | | Erro "Valor líquido não positivo" no seu código | As taxas somadas são maiores que a venda | Revise o valor da venda e as taxas lidas | | `fees` vem vazio | A subconta não tem taxas configuradas; as cobranças dela são recusadas com `422` `Fees not configured` | Fale com o suporte da Finvia para configurar as taxas | ## Perguntas frequentes > [accordion] Por que o percentual de split é maior que a minha comissão? > > Porque ele incide sobre o valor líquido, que é menor que o bruto. Para chegar ao mesmo valor em reais, o percentual sobre a base menor precisa ser maior. > [accordion] Preciso recalcular para cada venda? > > Sim, sempre que método, bandeira, parcelas ou valor mudarem. A taxa fixa pesa mais em vendas pequenas e o percentual transacional muda com as parcelas, então o percentual de split muda junto. > [accordion] Posso usar o split padrão da conta com comissão sobre o bruto? > > A regra padrão aplica um percentual fixo sobre o líquido de todas as vendas. Se a comissão é sobre o bruto e as taxas variam por venda, o valor recebido também varia. Para valor exato, envie o `split` calculado em cada cobrança. > [accordion] E se o vendedor antecipar os recebíveis? > > Com a base líquida, o split é recalculado sobre o valor já descontada a taxa de antecipação, e a plataforma recebe proporcionalmente menos. A base bruta e a opção de a master absorver a taxa de antecipação das subcontas existem sob consulta. > [accordion] Como confiro se o cálculo deu certo? > > Consulte a cobrança em `GET /v1/charges/{id}`: a lista `splits` traz `splitPercentage` e `referenceAmount` de cada recebedor. Depois da liquidação, compare o valor recebido com o valor alvo. A soma da taxa transacional, da parte da plataforma e da parte do vendedor precisa bater com o valor bruto quando não há antecipação. ## Como testar No [roteiro de homologação](/homologacao/roteiro), o cenário **SPL-05** pede a conferência de `splitPercentage` e da coerência com a base de cálculo (`referenceAmount`) em `GET /v1/charges/{id}`. Enquanto a cobrança não liquida, `splitAmount` pode vir menor que o valor da tabela, porque simula uma antecipação. Use a tabela de referência desta página para montar casos de teste com valores conhecidos. O **SPL-06** cobre Pix e cartão parcelado. ## Veja também > [card] [Split de pagamentos](/guias/fast-connect/split) > > Regras, relações permitidas e exemplos de requisição. > [card] [Taxas da subconta](/guias/fast-connect/taxas) > > Como ler a resposta de `fees-info`. > [card] [Taxas e dados (referência)](/referencia/fast-connect/taxas-e-dados) > > Referência completa da rota de taxas. > [card] [Marketplace e PSP](/casos-de-uso/marketplace-psp) > > Caso de uso com comissão por split. # Regras de credenciamento Source: https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento Regras da Finvia para PSPs e plataformas que usam o Connect: split, pré-validação, documentos do lojista, prazos de análise, motivos de recusa, chargeback e MCCs não aceitos. Estas são as regras da Finvia para PSPs (provedores de serviços de pagamento) e plataformas que credenciam lojistas como subcontas no [Connect](/guias/fast-connect/visao-geral). Elas valem para o cadastro do lojista, para as transações e para o tratamento de estornos, chargebacks e MED. Cada regra aparece junto do campo ou da rota da API em que ela se aplica. > [!NOTE] > > **Para o negócio:** monte o seu processo de credenciamento já com estas regras. Lojista com documentação completa e correta é analisado mais rápido, e um cadastro fora das regras é recusado. Compartilhe esta página com o time comercial e de risco que atende os lojistas. ## Quando usar * Antes de começar a credenciar lojistas como subcontas, para saber o que pedir a cada um. * Ao montar o formulário de cadastro da sua plataforma e a checagem interna antes do envio à Finvia. * Ao definir o split das transações de PSP e o fluxo de estorno. * Ao preparar o time para responder alertas de chargeback e de MED. ## Regras de transação | Regra | Detalhe | | - | - | | Split obrigatório para PSP | Toda transação de PSP deve ter split entre a conta master (PSP) e a subconta (lojista). Split de 100% para o PSP não é permitido. Veja [Split de pagamentos](/guias/fast-connect/split) | | 3D Secure em lojista de alto risco | O PSP deve usar 3D Secure quando o perfil do lojista for de alto risco de chargeback. A autenticação reduz o chargeback por fraude e por não reconhecimento da compra. Veja [3D Secure](/guias/3d-secure/visao-geral) | | Estorno só pela API | O reembolso (estorno) é feito só pela rota [`POST /v1/refunds`](/referencia/cobrancas/estornar). A Finvia não faz estorno por chamado ou pelo suporte, exceto em caso de erro sistêmico | > [!WARNING] > > Uma cobrança de PSP sem split, ou com 100% do valor destinado à conta master, descumpre estas regras. Envie o campo `split` em toda cobrança, ou configure uma regra de split padrão que divida o valor entre a master e a subconta do lojista. ## Regras de cadastro do lojista O desenho abaixo resume a pré-validação que o PSP faz antes de enviar o lojista e o que pode sair da análise da Finvia. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB IN(["Novo lojista"]):::neutro Q1{"MCC aceito e URL
mostra o que será
vendido?"}:::decisao NAO["Não envie à Finvia
o cadastro seria recusado"]:::erro Q3{"Tipo de
empresa?"}:::decisao PJ["Selfie com documento,
identidade frente e verso,
cartão CNPJ e contrato social"]:::neutro MEI["Cartão CNPJ pela API
e certificado de MEI
pelo suporte"]:::neutro Q5{"Documentos válidos?
sem passaporte, vencido
ou rasurado"}:::decisao AJ["Peça documentos
novos ao lojista"]:::alerta ENV["Envia à Finvia
POST /v1/submerchants
e os documentos"]:::lojista AN["Análise Finvia
automática e revisada
por pessoas, até 24 h"]:::finvia OK(["Aprovada
pre_approved e active"]):::ok COR(["correcting
ajuste pedido"]):::alerta REJ(["rejected
rejectionReason"]):::erro IN --> Q1 Q1 -->|"não"| NAO Q1 -->|"sim"| Q3 Q3 -->|"pessoa jurídica"| PJ Q3 -->|"MEI"| MEI PJ --> Q5 MEI --> Q5 Q5 -->|"não"| AJ Q5 -->|"sim"| ENV ENV --> AN AN --> OK AN --> COR AN --> REJ classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` No envio, informe também `website`, `averageMonthlyRevenue` e `averageOrderValue`. Quando o contrato social exige assinatura conjunta, cada signatário entra em `additionalRepresentatives` e recebe os próprios documentos. | Regra | Detalhe | | - | - | | Pré-validação pelo PSP | O PSP deve pré-validar o cadastro do lojista do lado dele antes de enviar à Finvia: dados, documentos e o que o lojista vende | | Documentos obrigatórios | A lista depende do tipo de empresa. Veja a tabela abaixo | | Documentos aceitos | Documentos vencidos ou rasurados não são aceitos | | Dados do negócio | É obrigatório informar a URL do lojista com o que será vendido, a expectativa de faturamento e o ticket médio | | Assinatura conjunta | Se o contrato social exige assinatura conjunta, é preciso enviar a documentação de todos os signatários | ### Documentos obrigatórios para cartão de crédito | Documento | Pessoa jurídica | MEI | Como enviar pela API (fieldname) | | - | - | - | - | | Selfie segurando o documento | Obrigatório | | `selfie_with_document` | | Documento de identificação, frente | Obrigatório | | `responsible_document_front` | | Documento de identificação, verso | Obrigatório | | `responsible_document_back` | | Cartão CNPJ | Obrigatório | Obrigatório | `cnpj_card` | | Contrato social | Obrigatório | | `social_contract` | | Certificado de MEI | | Obrigatório | Não há fieldname para este documento. Fale com o suporte da Finvia para enviá-lo | Documentos de identificação aceitos: CNH, CNH Digital, RG ou CNE. **Passaporte não é aceito.** Os arquivos vão em `POST /v1/submerchants/{id}/document` ou em `POST /v1/document-uploads` com token, em PDF ou imagem (JPG, PNG, GIF, BMP ou WebP), até 50 MB cada. Veja [Sócios e documentos](/guias/fast-connect/socios-e-documentos). > [!TIP] > > **Para o desenvolvedor:** quando o contrato social exige assinatura conjunta, cadastre cada signatário além do representante legal em `additionalRepresentatives` na criação da subconta. Depois, gere um [token de upload](/referencia/fast-connect/criar-token-upload) com o `legalRepresentativeId` de cada um e envie `responsible_document_front`, `responsible_document_back` e `selfie_with_document` de cada signatário. Sem o `legalRepresentativeId`, os documentos ficam no representante legal. ### Onde os dados do negócio entram no cadastro Os dados do negócio vão no corpo de [`POST /v1/submerchants`](/referencia/fast-connect/criar-subconta): | Exigência | Campo da API | Exemplo | | - | - | - | | URL do lojista com o que será vendido | `website` | `https://loja.exemplo.com.br` | | Descrição do que será vendido | `productDescription` | `Roupas e acessórios femininos` | | Expectativa de faturamento | `averageMonthlyRevenue` (faturamento médio mensal, em reais) | `30000` | | Ticket médio | `averageOrderValue` (em reais) | `150` | A URL precisa mostrar os produtos ou serviços que o lojista vai vender. Uma URL sem vínculo com o produto ou serviço é motivo de recusa. ## Análise e prazo | Item | Como funciona | | - | - | | Tempo médio | Até 24 horas. É mais rápido quando não há divergência documental | | Forma da análise | Automática e revisada por pessoas | | Documentos alterados ou inválidos | São recusados | | Acompanhamento | Pelo `status` da subconta e pelos avisos de mudança de status. Veja [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) | ### Motivos comuns de recusa * Processos criminais de sócios. * Documentos inválidos ou incorretos. * Produtos proibidos: golpes, réplicas, ou URL sem vínculo com o produto ou serviço. * Empresas inaptas. * Sócios sem poder de assinatura no contrato social. > [!NOTE] > > Uma recusa aparece na API como status `rejected` da subconta, com o motivo em `rejectionReason` no aviso de mudança de status. Um pedido de ajuste aparece como `correcting`. ## MCCs que não podem ser credenciados O MCC (Merchant Category Code) é o código que classifica o ramo de atividade do lojista nas bandeiras de cartão. Lojistas com os MCCs abaixo não podem ser credenciados: | MCCs não aceitos | | - | | `4816`, `5122`, `5816`, `5912`, `5966`, `5967`, `5968` | | `5993`, `6012`, `6051`, `6211`, `7273`, `7841`, `7995` | > [!WARNING] > > Confira o ramo do lojista na pré-validação. Enviar à Finvia um lojista com um desses MCCs leva à recusa do cadastro. ## Chargeback e MED | Item | Como funciona | | - | - | | Alerta | O alerta de chargeback ou de MED (Mecanismo Especial de Devolução do Pix) chega por e-mail à conta master, com os detalhes da contestação | | Defesa | A defesa e as evidências são enviadas em resposta a esse e-mail, dentro do prazo indicado nele | | Prazo | Contestação respondida fora do prazo é passível de perda, mesmo com todas as evidências | | Resultado | Depende do emissor e segue o fluxo das bandeiras | O desenho abaixo mostra o caminho de uma contestação, do alerta ao resultado. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB AL["Alerta de chargeback
ou MED por e-mail
à conta master"]:::finvia API["Na API, a cobrança aparece
bloqueada ou com o
status atualizado"]:::alerta DEF["Defesa e evidências
em resposta ao e-mail"]:::lojista Q{"Resposta dentro do
prazo do e-mail?"}:::decisao EMI["Emissor decide
pelo fluxo das bandeiras"]:::externo PER(["Passível de perda,
mesmo com evidências"]):::erro AL -.-> API AL --> DEF DEF --> Q Q -->|"sim"| EMI Q -->|"não"| PER classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 ``` Não há rota de API para enviar a defesa. Na API, a cobrança contestada aparece bloqueada ou com o status atualizado. Veja [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ### Pré-alerta de chargeback | Item | Como funciona | | - | - | | O que é | Alerta de que o titular contestou a compra, antes de o chargeback ser formalizado | | Reembolso automático | Quando previsto em contrato, o alerta vem com o reembolso automático da cobrança | | Custo | O custo do serviço de pré-alerta (Ethoca/Verifi) é debitado da conta | ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Subconta recusada (`rejected`) | Documento inválido, empresa inapta, produto proibido, MCC não aceito ou sócio sem poder de assinatura | Confira os motivos desta página e faça a pré-validação antes de enviar | | Subconta em `correcting` | A Finvia pediu ajuste de dados ou documentos | Leia o `rejectionReason` do aviso e reenvie o que foi pedido | | Documento de identidade recusado | Passaporte, documento vencido ou rasurado | Envie CNH, CNH Digital, RG ou CNE válidos e legíveis | | Cadastro de MEI parado | Falta o certificado de MEI, que não tem campo na API | Fale com o suporte da Finvia para enviar o certificado | | Documentos de um signatário faltando | Contrato com assinatura conjunta e documentos enviados só do representante legal | Cadastre os signatários em `additionalRepresentatives` e envie os documentos de cada um com token | | Pedido de estorno pelo suporte não atendido | O estorno é feito só pela API | Use `POST /v1/refunds` | | Contestação perdida mesmo com evidências | Resposta enviada fora do prazo do e-mail de alerta | Responda o e-mail de alerta dentro do prazo indicado | ## Perguntas frequentes > [accordion] Posso ficar com 100% do valor como PSP? > > Não. Toda transação de PSP precisa de split entre a conta master (PSP) e a subconta (lojista), e o split de 100% para o PSP não é permitido. > [accordion] O passaporte serve como documento de identificação? > > Não. São aceitos CNH, CNH Digital, RG ou CNE. Documentos vencidos ou rasurados também não são aceitos. > [accordion] Quanto tempo leva o credenciamento? > > Em média, até 24 horas. Sem divergência nos documentos, a análise é mais rápida. A análise é automática e revisada por pessoas. > [accordion] Como envio o certificado de MEI? > > A API não tem campo para esse documento. Envie o cartão CNPJ pela API (`cnpj_card`) e fale com o suporte da Finvia para enviar o certificado de MEI. > [accordion] A Finvia faz o estorno se eu abrir um chamado? > > Não. O estorno é feito só pela rota `POST /v1/refunds`. A exceção é o erro sistêmico. > [accordion] Como respondo a um chargeback ou MED? > > Responda o e-mail de alerta recebido pela conta master, com a defesa e as evidências, dentro do prazo indicado. O resultado depende do emissor e segue o fluxo das bandeiras. ## Como testar No [roteiro de homologação](/homologacao/roteiro), os cenários **FC-01** (criação da subconta com `website`, `averageMonthlyRevenue` e `averageOrderValue`) e **FC-02** (envio de cada documento) cobrem o cadastro. Os cenários **SPL-01** a **SPL-06** cobrem o split que toda transação de PSP precisa ter. ## Veja também > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Cadastro, documentos e status de aprovação. > [card] [Sócios e documentos](/guias/fast-connect/socios-e-documentos) > > Documentos de cada sócio e signatário com token. > [card] [Split de pagamentos](/guias/fast-connect/split) > > Divisão do valor entre a master e a subconta. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > Como a contestação aparece na API. # Saques da subconta Source: https://docs.fastpaybrasil.com/guias/fast-connect/saques A conta master solicita o saque do saldo de cada subconta, enviado por Pix para a chave CNPJ dela, com taxa calculada na criação e aviso de aprovação ou recusa. Com o Connect, a conta master solicita o saque (payout) do saldo disponível de cada subconta. O dinheiro vai por Pix para a **chave Pix CNPJ da própria subconta**, sempre em reais. A taxa de saque é calculada na criação do pedido, todo saque de subconta passa por aprovação manual da operação Finvia, e o resultado chega por webhook e pela listagem. ## Quando usar * **Vendedor de marketplace** que quer retirar o que vendeu: a sua plataforma oferece um botão "sacar" e cria o pedido pela API. * **Repasse periódico** a lojistas de um PSP: a sua aplicação cria pedidos de saque conforme a regra combinada com cada lojista. * **Painel financeiro do vendedor**: a sua plataforma lista os saques com status, taxa e [valor líquido](/glossario) (o valor do saque menos a taxa). Esta página trata do saque de **subconta**. O saque do saldo da própria conta (master ou não) usa [`POST /v1/payout-requests`](/referencia/saques/criar) e está em [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento). A master também pode sacar o próprio saldo pela rota de subconta, passando o próprio `id` no caminho. ## Como funciona O desenho abaixo mostra um saque de subconta do pedido ao aviso, com os dois resultados possíveis. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(243,245,248) Sua aplicação participant APP as Seu servidor (master) participant WH as Seu receptor de webhooks end box rgb(234,243,255) Finvia participant API as Finvia API participant OP as Operação Finvia end box rgb(244,240,255) Fora da Finvia participant BCO as Banco da subconta (chave Pix CNPJ) end APP->>API: POST /v1/submerchants/{merchantId}/payout-requests · amount 1500 (em reais) Note over API: Confere subconta, saldo e limite · calcula a taxa · valor bruto sai do saldo API-->>APP: 201 · só o id do pedido (nasce pending) API->>OP: Pedido aguarda decisão manual alt aprovado OP->>API: approved API->>BCO: Pix do valor líquido (amount menos payoutFee) API-)WH: Webhook payout.approved · netAmount else recusado OP->>API: rejected Note over API: Valor volta ao saldo disponível API-)WH: Webhook payout.rejected · rejectionReason end WH->>API: GET /v1/payout-requests · filtro merchantId API-->>WH: status approved ou rejected ``` O webhook de saque não tem assinatura: confirme o status pela listagem antes de agir, como no último passo do desenho. **1. Pedido de saque** Sua aplicação chama `POST /v1/submerchants/{merchantId}/payout-requests` com a chave secreta da conta master e o valor em reais. **2. Validação e reserva do valor** A Finvia confere a subconta (ativa, sem bloqueio, com CNPJ e saques habilitados), o saldo disponível e o limite por saque, calcula a taxa de saque (fixa mais percentual) e cria o pedido com status `pending`. O valor bruto sai do saldo disponível nesse momento. A resposta traz o `id` do pedido. **3. Aprovação ou recusa** A operação Finvia aprova (`approved`) ou recusa (`rejected`) o pedido. Na aprovação, o Pix do valor líquido é enviado para a chave CNPJ da subconta. Na recusa, o valor volta ao saldo disponível. **4. Aviso** Os webhooks `payout.approved` e `payout.rejected` vão para os endpoints cadastrados na subconta e para os endpoints da master cadastrados com a opção de incluir subcontas. ## Pré-requisitos | O que precisa estar pronto | Como você percebe se faltar | | - | - | | Módulo Connect habilitado pela Finvia na conta master | `403` com `Fast Connect not enabled.` | | Chave da master gerada por usuário com permissão de saque (a chave padrão da conta serve) | `403` com `Acesso negado` (ex.: perfil Desenvolvedor) | | Chave de produção | `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` com a chave de teste | | Subconta vinculada à sua conta master | `404` com `SubMerchant not found` | | Subconta com status `active` e sem bloqueio | `422` com `SubMerchant account is not active` ou `SubMerchant is blocked. Withdrawals are not allowed.` | | CNPJ cadastrado na subconta | `422` com `SubMerchant CNPJ not configured` | | Taxa de saque configurada pela Finvia | `422` com `Payout fees not configured` | | CNPJ da subconta cadastrado como **chave Pix** em uma conta bancária da empresa | A API não confere. Sem a chave, o Pix não é concluído | | Endpoints de webhook na subconta, ou na master com a opção de incluir subcontas | Nenhum aviso chega | > [!NOTE] > > **Para o negócio:** o saque é enviado por Pix para a chave CNPJ da subconta (o mesmo CNPJ do cadastro). Antes de liberar o saque, cada vendedor precisa cadastrar esse CNPJ como chave Pix em uma conta bancária da empresa; não é possível escolher outra chave. A taxa de saque é uma condição comercial definida com a Finvia: mostre ao vendedor quanto ele vai receber já descontada a taxa. ## Regras de negócio | Regra | Detalhe | | - | - | | Valor | Em **reais**, com casas decimais: `100` = R\$ 100,00 e `100.50` = R\$ 100,50 | | Mínimo | R\$ 1,00 por saque (`amount` mínimo `1`) | | Máximo | Limite máximo por saque configurado para a conta (`422` `Maximum withdrawal amount is X BRL`) | | Moeda | Sempre `BRL` | | Destino | Sempre Pix, na chave CNPJ da subconta | | Saldo | O saldo disponível precisa cobrir o valor. O valor bruto sai do saldo na criação | | Pendentes | Só um saque `pending` por vez, por moeda (`422` `You already have a pending withdrawal request for this currency`) | | Taxa | Calculada na criação: taxa fixa mais percentual sobre o valor pedido | | Aprovação | Sempre manual, pela operação Finvia | | Modo Teste | Não existe saque com a chave de teste (`403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`) | | Aviso | Webhook para os endpoints da subconta e para os da master com a opção de incluir subcontas | > [!WARNING] > > O valor vai em **reais**. Enviar `10000` pensando em R\$ 100,00 cria um pedido de saque de R\$ 10.000,00. ## Cálculo da taxa A taxa é calculada automaticamente quando o pedido é criado: ```text theme={null} payoutFee = taxa fixa + (amount × taxa percentual ÷ 100) netAmount = amount − payoutFee ``` Exemplo com uma taxa ilustrativa de R\$ 2,00 fixa mais 0,5%, em um saque de R\$ 1.500,00: | Etapa | Conta | Resultado | | - | - | - | | Parte percentual | 1.500 × 0,5 ÷ 100 | R\$ 7,50 | | Taxa total | 2,00 + 7,50 | R\$ 9,50 | | Valor líquido | 1.500,00 − 9,50 | R\$ 1.490,50 | Na listagem e nos webhooks, os valores chegam como **texto decimal com 8 casas**, em reais: `amount` `"1500.00000000"`, `payoutFee` `"9.50000000"` e, no webhook, `netAmount` `"1490.50000000"`. Converta para número antes de calcular e não divida por 100. ## Status do saque | Status | Significado | | - | - | | `pending` | Pedido criado. O valor bruto já saiu do saldo disponível e aguarda decisão | | `approved` | Aprovado e enviado para pagamento. O Pix do valor líquido é enviado nesse momento. `processedAt` é preenchido | | `rejected` | Recusado. O valor volta ao saldo disponível. `rejectionReason` e `processedAt` são preenchidos | `approved` significa aprovado e enviado para pagamento. O dinheiro pode ainda não ter chegado à conta de destino. O desenho abaixo mostra o ciclo de status do pedido de saque e o que acontece com o saldo em cada etapa. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Pedido de saque
amount em reais"]):::lojista VAL{"Passou nas
validações?"}:::decisao ERR["Erro 400, 403, 404 ou 422
nenhum saque é criado"]:::erro PEN["pending
pendente
valor bruto sai do saldo"]:::alerta APR["approved
aprovado"]:::ok REJ["rejected
recusado"]:::erro PIX["Pix do valor líquido
para a chave CNPJ"]:::externo VOLTA["Valor volta ao
saldo disponível"]:::neutro EVA[["payout.approved"]]:::evento EVR[["payout.rejected
com rejectionReason"]]:::evento INI --> VAL VAL -->|"não"| ERR VAL -->|"sim · 201 com id"| PEN PEN -->|"operação Finvia aprova"| APR PEN -->|"operação Finvia recusa"| REJ APR ==> PIX REJ --> VOLTA APR -.->|"webhook"| EVA REJ -.->|"webhook"| EVR classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Os webhooks só existem para saques de subconta. O saque da própria conta (master ou não) não gera webhook: acompanhe pela listagem. ## Passo a passo ### 1. Crie o pedido de saque ```http REST (JSON) theme={null} POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 1500 } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 1500 }' ``` ```javascript Node.js theme={null} const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); // chave da master const subcontaId = '36OO3bcGjhPjjF3tzrqOGcmQuKo'; const response = await fetch( `https://api-global.fastpaybrasil.com/v1/submerchants/${subcontaId}/payout-requests`, { method: 'POST', headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 1500 }), // R$ 1.500,00, em reais }, ); const result = await response.json(); if (response.status === 201) { console.log('Saque criado:', result.id); // guarde o id para conciliar com o webhook } else { console.error(response.status, result.message); // ex.: "SubMerchant account is not active" } ``` ```python Python theme={null} import os import requests payload = { "amount": 1500, } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 1500, ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 1500 } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 1500 } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 1500 }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 1500, }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201`: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI" } ``` ### 2. Acompanhe pela listagem `GET /v1/payout-requests` lista os pedidos, do mais recente para o mais antigo. Para a conta master, a lista inclui os saques das subcontas; filtre por `merchantId` para ver uma conta só. | Filtro | Uso | | - | - | | `merchantId` | Pedidos de uma conta (sua ou de uma subconta) | | `status` | `pending`, `approved` ou `rejected` | | `currency` | Moeda (ex.: `BRL`) | | `createdAtStart`, `createdAtEnd` | Período de criação, datas inclusivas no formato `AAAA-MM-DD` | | `page`, `size` | Página (padrão `1`) e itens por página (padrão `10`) | A API ignora parâmetros desconhecidos sem erro: filtros como `createdAt` ou `processedAt` não existem e não filtram nada. ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&page=1&size=20" \ -u "$FINVIA_API_KEY:" ``` ```json 200 theme={null} { "data": [ { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "amount": "1500.00000000", "currency": "BRL", "status": "pending", "payoutFee": "9.50000000", "externalAccountDetails": { "type": "pix", "pix_key": "11222333000181" }, "processedAt": null, "createdAt": "2026-10-20T18:45:52.988Z", "merchantLegalName": "LOJA EXEMPLO LTDA", "merchantEmail": "financeiro@lojaexemplo.com.br" } ], "total": 1, "page": 1, "size": 20, "pages": 1, "pendingCount": 1 } ``` `pendingCount` traz o total de pedidos `pending` com os mesmos filtros (sem considerar o filtro `status`), útil para um indicador de "saques aguardando" no seu painel. A listagem não traz `netAmount` nem `rejectionReason`: o líquido é `amount` menos `payoutFee`, e o motivo da recusa chega no webhook `payout.rejected`. A listagem é a única forma de consultar saques: não há consulta individual para contas merchant. ### 3. Receba o aviso de aprovação ou recusa Quando o pedido é aprovado ou recusado, a Finvia envia um webhook: | Evento | Quando | | - | - | | `payout.approved` | O saque foi aprovado e o Pix do valor líquido foi enviado para pagamento | | `payout.rejected` | O saque foi recusado. O motivo vem em `data.rejectionReason` | Não há evento de criação de saque. ```json payout.rejected theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "event": "payout.rejected", "data": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "amount": "100.00000000", "currency": "BRL", "status": "rejected", "payoutFee": "1.00000000", "netAmount": "99.00000000", "rejectionReason": "Documentação incompleta" } } ``` O `id` da raiz é o `id` do saque, igual a `data.id`, e se repete nos eventos do mesmo saque: use `id` + `event` para descartar avisos repetidos. Os webhooks de saque usam camelCase e não têm `livemode`. > [!WARNING] > > Os avisos de saque vão para os endpoints de webhook cadastrados na subconta e também para os endpoints da master cadastrados com a opção de incluir subcontas (no painel, em **Configurações** > **Webhooks** da conta selecionada). O webhook de saque não tem cabeçalho de assinatura: confirme o status pela listagem antes de agir. Saque da própria conta (master ou não) não gera webhook. **Em validação (V-49):** o suporte está definindo o procedimento quando o Pix do saque falha (prazo e como o saldo volta). A API não confere se o CNPJ está cadastrado como chave Pix; se não estiver, o Pix não é concluído e o status do saque não mostra a falha (ele pode continuar `pending` ou aparecer como `approved`). Enquanto isso, se o vendedor não receber, abra um chamado com o `id` do saque. Formato completo e exemplo de implementação em [Webhooks de saque](/guias/webhooks/saque). ## Erros comuns | HTTP | Mensagem | Causa | Como resolver | | - | - | - | - | | `400` | `["amount must be a positive number", "amount must not be less than 1"]` | Valor ausente, zero ou abaixo de R\$ 1,00 | Envie `amount` a partir de `1` | | `401` | `Unauthorized` | Chave ausente ou inválida | Confira a chave e o formato do Basic | | `403` | `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chave de teste | Saques só existem em produção | | `403` | `Acesso negado` | Chave de usuário sem permissão de saque (ex.: Desenvolvedor) | Use a chave padrão da conta master | | `403` | `Fast Connect not enabled.` | Módulo não habilitado na conta master | Peça a liberação à Finvia | | `404` | `SubMerchant not found` | Subconta inexistente ou de outra conta master | Confira o `merchantId` | | `422` | `SubMerchant account is not active` | Subconta não está `active` | Aguarde a aprovação ou verifique o status | | `422` | `SubMerchant is blocked. Withdrawals are not allowed.` | Subconta bloqueada | Fale com a Finvia | | `422` | `Withdrawals are disabled for this submerchant` | Saques desabilitados para a subconta | Fale com a Finvia | | `422` | `SubMerchant CNPJ not configured` | Subconta sem CNPJ cadastrado | Fale com a Finvia para completar o cadastro | | `422` | `Insufficient balance. Required: X, Available: Y` | Saldo disponível menor que o valor | Peça um valor menor | | `422` | `Maximum withdrawal amount is X BRL` | Valor acima do limite por saque | Divida em saques menores, um de cada vez | | `422` | `You already have a pending withdrawal request for this currency` | Saque anterior ainda pendente | Aguarde a decisão | | `422` | `Merchant settings are not configured correctly` | Configuração da conta incompleta | Fale com a Finvia | | `422` | `Payout fees not configured` | Taxa de saque não configurada | Peça à Finvia a configuração da taxa de saque | | Saque muito maior que o pretendido | | Valor enviado em centavos | Envie em reais | As mensagens vêm em inglês. Trate o erro pelo código HTTP e use a mensagem só para registro ou exibição. ## Perguntas frequentes > [accordion] Posso escolher outra chave Pix ou uma conta bancária? > > Não. O destino é sempre a chave Pix CNPJ da subconta. Na listagem, isso aparece em `externalAccountDetails` como `{ "type": "pix", "pix_key": "" }`. > [accordion] Qual é o valor mínimo de saque? > > R\$ 1,00. O campo `amount` aceita casas decimais, como `100.50` para R\$ 100,50. > [accordion] Quanto tempo leva para o dinheiro cair? > > O saque de subconta passa por aprovação manual da operação Finvia. O Pix é enviado quando o pedido é aprovado. Combine com os vendedores que o dinheiro não cai no momento do pedido. > [accordion] Como mostro ao vendedor quanto ele vai receber? > > Depois de criar o pedido, consulte a listagem filtrando por `merchantId`. Cada pedido traz `amount` e `payoutFee`; o líquido é a diferença. O webhook de aprovação traz também `netAmount`. > [accordion] A conta master é avisada dos saques das subcontas? > > Sim, se tiver um endpoint de webhook cadastrado com a opção de incluir subcontas. Sem isso, os avisos vão só para os endpoints da subconta. A master também acompanha todos os saques pela listagem `GET /v1/payout-requests`, que traz `merchantLegalName` e `merchantEmail` de cada pedido. > [accordion] Consigo testar o saque no Modo Teste? > > Não. Com a chave de teste, a criação responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`, e a listagem só traz registros de teste (na prática, vazia). ## Como testar No [roteiro de homologação](/homologacao/roteiro), o cenário **FC-07** confere o saque da subconta com valor em **reais**: a requisição montada, o tratamento da resposta `{ "id" }` e dos erros documentados. Como não existe saque com a chave de teste, o cenário não é executado no Modo Teste. ## Veja também > [card] [Webhooks de saque](/guias/webhooks/saque) > > Envelope, campos e implementação. > [card] [Criar saque da subconta](/referencia/fast-connect/criar-saque) > > Referência da rota de criação. > [card] [Listar saques](/referencia/saques/listar) > > Referência da listagem e dos filtros. > [card] [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento) > > Saldo por moeda e saque da própria conta. # Sócios e documentos Source: https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos Cadastre todos os sócios da subconta, envie os documentos de cada um com um token de upload e acompanhe a análise de cada documento. Empresas com mais de um sócio podem ser cadastradas com todos eles de uma vez. Cada sócio recebe um identificador próprio, e os documentos de pessoa (identidade e selfie) ficam vinculados ao sócio certo. Para coletar esses documentos, a Finvia oferece um **token de upload**: uma credencial temporária, de 5 minutos, que permite enviar os arquivos direto do navegador do vendedor sem expor a sua chave secreta. ## Quando usar | Situação | Caminho | | - | - | | Empresa com um único representante, documentos coletados no seu servidor | Upload direto em `POST /v1/submerchants/{id}/document` ([Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc)) | | Empresa com sócios além do representante legal | Cadastro com `additionalRepresentatives` e upload com token, um token por sócio | | Vendedor envia os documentos pelo navegador, no seu formulário de cadastro | Upload com token, mesmo com um único representante | | Conferir quais documentos de cada sócio já foram enviados e analisados | `GET /v1/submerchants/{merchantId}/legal-representatives?include=documents` | > [!NOTE] > > **Para o negócio:** com o token, o arquivo vai do computador ou celular do vendedor direto para a Finvia. A sua plataforma não precisa receber nem armazenar fotos de documentos de identidade, e a chave secreta continua guardada no seu servidor. ## Como funciona A sequência abaixo mostra o envio com token: o seu servidor emite o token e o navegador do sócio manda os arquivos direto para a Finvia. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Vendedor participant V as Navegador do sócio end box rgb(243,245,248) Sua aplicação participant S as Seu servidor (master) end box rgb(234,243,255) Finvia participant F as Finvia API end S->>F: POST /v1/submerchants (legalRepresentative e additionalRepresentatives) F-->>S: 201 · id · legalRepresentatives[] com isPrimary Note over S: Guarde o id de cada sócio loop Para cada sócio, a cada envio V->>S: Escolhe os arquivos e pede um token S->>F: POST .../document/upload-token (legalRepresentativeId) F-->>S: 201 · token · expiresIn 300 S-->>V: Só o token, nunca a chave secreta V->>F: POST /v1/document-uploads · Bearer token · multipart alt Envio aceito F-->>V: 201 sem corpo else Token vencido ou inválido F-->>V: 401 else Token já usado F-->>V: 403 else Arquivo recusado F-->>V: 400, 413, 415 ou 422 com o código em error end end S->>F: GET legal-representatives com include=documents F-->>S: Documentos por sócio · approved, rejected ou pending ``` **1. Cadastre os sócios** Na criação da subconta, envie o representante legal em `legalRepresentative` e os demais sócios em `additionalRepresentatives`. **2. Guarde os ids** A resposta traz `legalRepresentatives[]`: o representante legal primeiro, com `isPrimary: true`, e depois os sócios na ordem enviada, com `isPrimary: false`. **3. Emita um token por sócio** No seu servidor, chame `POST /v1/submerchants/{merchantId}/document/upload-token` com o `legalRepresentativeId` do sócio. O token vale 300 segundos. **4. Envie os arquivos com o token** O navegador (ou o seu servidor) envia os arquivos para `POST /v1/document-uploads` com `Authorization: Bearer` e o token. A subconta e o sócio vêm de dentro do token. **5. Confira os documentos** Liste os representantes com `include=documents` para ver o que foi enviado e o status de análise de cada documento. ## Regras de negócio | Regra | Detalhe | | - | - | | Representante legal | `legalRepresentative` é obrigatório e é sempre o representante legal da subconta (`isPrimary: true`) | | Sócios adicionais | Opcionais. Mesmo formato do representante legal. São cadastrados como sócios não representantes | | Documentos no cadastro | Não vão no corpo da criação. São enviados depois, pelas rotas de upload | | Upload direto | `POST /v1/submerchants/{id}/document` vincula documentos de pessoa sempre ao representante legal | | Token sem `legalRepresentativeId` | Os documentos de pessoa vinculam ao representante legal | | `legalRepresentativeId` de outra subconta | Resposta `404` com "Representante legal não encontrado" | | Validade do token | 300 segundos (5 minutos), uso único | | Reenvio | Reenviar um documento de pessoa substitui apenas o documento daquele sócio. A listagem mostra só o mais recente de cada tipo, por sócio | | Documentos antigos | Documentos enviados antes do cadastro de sócios ficam com o representante legal | | Documentos de empresa | `cnpj_card`, `social_contract` e `irs_letter` valem para a subconta inteira, por qualquer rota | | Arquivos | JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF, até 50 MB cada | | Subconta aprovada | Os documentos não podem mais ser alterados (`422`) | | URLs dos documentos | Assinadas e válidas por 1 hora. Não armazene | ## Documentos de empresa e de pessoa | Campo (fieldname) | Documento | Tipo | Vínculo | | - | - | - | - | | `cnpj_card` | Cartão CNPJ | Empresa | Subconta inteira | | `social_contract` | Contrato social | Empresa | Subconta inteira | | `irs_letter` | IRS letter, usada no fluxo de cadastro de LLC | Empresa | Subconta inteira | | `responsible_document_front` | Documento de identidade, frente | Pessoa | Sócio do token (ou representante legal) | | `responsible_document_back` | Documento de identidade, verso | Pessoa | Sócio do token (ou representante legal) | | `selfie_with_document` | Selfie segurando o documento | Pessoa | Sócio do token (ou representante legal) | > [!NOTE] > > O nome de cada campo do formulário multipart é o próprio nome do documento. Use exatamente os nomes da tabela acima: outro nome é recusado com `400`. Não há campo para o certificado de MEI; para enviá-lo, fale com o suporte da Finvia. A lista de documentos que o credenciamento exige está em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). O desenho abaixo mostra a quem cada documento fica vinculado, conforme o tipo e a rota de envio. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB DOC{"Tipo do
documento?"}:::decisao SUB(["Vale para a
subconta inteira"]):::ok ROTA{"Rota de
envio?"}:::decisao TK{"Token com
o id do sócio?"}:::decisao RL(["Fica com o
representante legal"]):::alerta SOC(["Fica com o
sócio do token"]):::ok DOC -->|"empresa: cnpj_card,
social_contract ou irs_letter
por qualquer rota"| SUB DOC -->|"pessoa: identidade
frente e verso ou selfie"| ROTA ROTA -->|"direta
.../{id}/document"| RL ROTA -->|"com token
/v1/document-uploads"| TK TK -->|"não"| RL TK -->|"sim, legalRepresentativeId"| SOC classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 ``` Na listagem de representantes, os documentos de pessoa aparecem com outros nomes de chave em `documents`: | Fieldname do upload | Chave em `documents` | | - | - | | `responsible_document_front` | `idFront` | | `responsible_document_back` | `idBack` | | `selfie_with_document` | `selfie` | Os documentos de empresa não aparecem nessa listagem. ## Passo a passo ### 1. Crie a subconta com os sócios Trecho do corpo de `POST /v1/submerchants` com o bloco de sócios. Os demais campos obrigatórios (empresa, endereço, telefones, conta bancária, acesso ao painel) estão em [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc). ```json theme={null} { "legalRepresentative": { "fullName": "Ana Lima", "idNumber": "52998224725", "idType": "cpf", "issuingCountry": "BRA", "dateOfBirth": "1985-04-20", "nationality": "Brasileira", "email": "ana@email.com", "motherName": "Maria Souza Lima", "gender": "F", "phones": [{ "type": "mobile", "number": "+5511987654321" }] }, "additionalRepresentatives": [ { "fullName": "Joao Silva", "idNumber": "11144477735", "idType": "cpf", "issuingCountry": "BRA", "dateOfBirth": "1985-05-10", "nationality": "Brasileira", "email": "joao@email.com", "motherName": "Maria Silva", "gender": "M", "phones": [{ "type": "mobile", "number": "+5511912345678" }] } ] } ``` O CPF de cada pessoa (`idNumber`) é validado com dígitos verificadores quando `issuingCountry` é `BRA` ou não é enviado. Use o CPF real de cada pessoa. O país vai em ISO 3166-1 alpha-3 (`BRA`); `BR` é recusado. Resposta `201`: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "legalRepresentatives": [ { "id": "2vorkEaaaBbbCccDddEeeFffGgg", "fullName": "Ana Lima", "isPrimary": true }, { "id": "2vorkEbbbCccDddEeeFffGggHhh", "fullName": "Joao Silva", "isPrimary": false } ] } ``` > [!TIP] > > **Para o desenvolvedor:** relacione cada id de `legalRepresentatives` ao sócio correspondente no seu banco. A ordem é sempre o representante legal primeiro e depois os sócios na ordem em que você enviou. Se perder os ids, recupere com `GET /v1/submerchants/{merchantId}/legal-representatives`. ### 2. Emita o token de upload (no servidor) ```http REST (JSON) theme={null} POST /v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }' ``` ```javascript Node.js (rota do seu backend) theme={null} // Exemplo com Express: o front pede um token para um sócio específico app.post('/api/subcontas/:subcontaId/socios/:socioId/upload-token', async (req, res) => { // Confira aqui se o usuário logado pode enviar documentos dessa subconta const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( `https://api-global.fastpaybrasil.com/v1/submerchants/${req.params.subcontaId}/document/upload-token`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ legalRepresentativeId: req.params.socioId }), }, ); const { token, expiresIn } = await response.json(); res.json({ token, expiresIn }); // nunca devolva a chave secreta ao front }); ``` ```python Python theme={null} import os import requests payload = { "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2vorkEbbbCccDddEeeFffGggHhh', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document/upload-token") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "legalRepresentativeId" => "2vorkEbbbCccDddEeeFffGggHhh", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201`: ```json theme={null} { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 300 } ``` Para vincular os documentos ao representante legal, envie a requisição sem corpo ou sem o campo `legalRepresentativeId`. ### 3. Envie os arquivos direto do navegador O navegador usa o token no cabeçalho `Authorization: Bearer`. A chave de API não aparece em nenhum momento no front-end. ```javascript Navegador (fetch + FormData) theme={null} async function enviarDocumentosDoSocio(subcontaId, socioId, arquivos) { // 1. Pede ao seu backend um token novo (válido por 300 segundos) const tokenResp = await fetch( `/api/subcontas/${subcontaId}/socios/${socioId}/upload-token`, { method: 'POST' }, ); const { token } = await tokenResp.json(); // 2. Monta o multipart: o nome do campo é o nome do documento const form = new FormData(); form.append('responsible_document_front', arquivos.frente); form.append('responsible_document_back', arquivos.verso); form.append('selfie_with_document', arquivos.selfie); // 3. Envia direto para a Finvia. Não defina Content-Type: o navegador monta o boundary const resp = await fetch('https://api-global.fastpaybrasil.com/v1/document-uploads', { method: 'POST', headers: { Authorization: `Bearer ${token}` }, body: form, }); if (resp.status === 201) return; const erro = await resp.json(); // Erros do arquivo trazem o código em `error` (ex.: FILE_TOO_LARGE); erros do token, o formato padrão throw new Error(`${resp.status}: ${erro.error ?? ''} ${erro.message}`); } // Uso com inputs de arquivo do formulário const arquivos = { frente: document.querySelector('#doc-frente').files[0], verso: document.querySelector('#doc-verso').files[0], selfie: document.querySelector('#selfie').files[0], }; await enviarDocumentosDoSocio('2vorkDcXyvzifL63YX09S9VqcnI', '2vorkEbbbCccDddEeeFffGggHhh', arquivos); ``` O mesmo envio pelo terminal, útil para testar: ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/document-uploads" \ -H "Authorization: Bearer $UPLOAD_TOKEN" \ -F "responsible_document_front=@joao-rg-frente.jpg" \ -F "responsible_document_back=@joao-rg-verso.jpg" \ -F "selfie_with_document=@joao-selfie.jpg" ``` A resposta de sucesso é `201`, sem corpo. > [!WARNING] > > Peça o token **no momento do envio**, depois que o vendedor escolheu os arquivos. O token expira em 5 minutos e vale para um único envio. Token vencido volta `401` "Token de upload inválido ou expirado"; token já usado volta `403` "Token de upload expirado ou já utilizado". ### 4. Liste os sócios e os documentos ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/legal-representatives?include=documents" \ -u "$FINVIA_API_KEY:" ``` ```json 200 theme={null} { "data": [ { "id": "2vorkEaaaBbbCccDddEeeFffGgg", "fullName": "Ana Lima", "idNumber": "52998224725", "email": "ana@email.com", "isPrimary": true, "documents": { "idFront": { "id": "2vorkEdddEeeFffGggHhhIiiJjj", "url": "https:///documents/abc123?X-Amz-Signature=...", "status": "approved", "rejectionReason": null, "createdAt": "2026-08-05T14:30:00.000Z" }, "idBack": { "id": "2vorkEeeeFffGggHhhIiiJjjKkk", "url": "https:///documents/def456?X-Amz-Signature=...", "status": "approved", "rejectionReason": null, "createdAt": "2026-08-05T14:30:00.000Z" }, "selfie": { "id": "2vorkEfffGggHhhIiiJjjKkkLll", "url": "https:///documents/ghi789?X-Amz-Signature=...", "status": "rejected", "rejectionReason": "Selfie sem o documento visível", "createdAt": "2026-08-05T14:30:00.000Z" } } }, { "id": "2vorkEbbbCccDddEeeFffGggHhh", "fullName": "Joao Silva", "idNumber": "11144477735", "email": "joao@email.com", "isPrimary": false, "documents": { "idFront": { "id": "2vorkEgggHhhIiiJjjKkkLllMmm", "url": "https:///documents/jkl012?X-Amz-Signature=...", "status": "pending", "rejectionReason": null, "createdAt": "2026-08-05T14:30:00.000Z" } } } ] } ``` Como ler a resposta: | Campo | Significado | | - | - | | `isPrimary` | `true` só no representante legal | | `documents` | Aparece apenas com `include=documents` e pode vir vazio (`{}`) | | `documents.idFront`, `idBack`, `selfie` | Documento de identidade frente, verso e selfie. **Chave ausente significa documento não enviado.** No exemplo, Joao Silva ainda não enviou o verso nem a selfie | | `status` | Situação da análise do documento: `approved` se aprovado, `rejected` se reprovado, `pending` nos demais casos | | `rejectionReason` | Motivo da rejeição, quando `status` é `rejected` | | `url` | Link assinado para ver o arquivo. Expira em 1 hora | > [!WARNING] > > Não grave a `url` dos documentos no seu banco. Ela expira em 1 hora. Quando precisar mostrar o arquivo, consulte a listagem de novo. > [!TIP] > > **Para o desenvolvedor:** use esta listagem para montar uma tela de pendências por sócio: documento ausente, em análise, aprovado ou rejeitado com motivo. Quando um documento de pessoa for rejeitado, emita um token para aquele sócio e reenvie só o documento rejeitado. O reenvio substitui apenas o documento daquele sócio. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` com "Representante legal não encontrado" ao emitir o token | `legalRepresentativeId` não pertence à subconta | Use um id devolvido em `legalRepresentatives` ou na listagem de representantes da mesma subconta | | `401` no `POST /v1/document-uploads` | Token vencido, inválido ou ausente | Emita um token novo logo antes do envio e use `Authorization: Bearer` | | `403` "Token de upload expirado ou já utilizado" | O token já foi usado | Emita um token para cada envio | | `400` `NO_FILE_SENT` ou `INVALID_DOCUMENT_NAME` | Nenhum arquivo no multipart, ou nome de campo fora da lista | Confira se os campos têm arquivo e se o nome do campo é um dos seis documentos | | `413` `FILE_TOO_LARGE` ou `415` `UNSUPPORTED_FILE_TYPE` | Arquivo acima de 50 MB ou formato não aceito | Use PDF ou imagem (JPG, PNG, GIF, BMP ou WebP) até 50 MB | | `422` `DOCUMENT_NOT_EDITABLE` | Subconta já aprovada | Fale com a Finvia se precisar atualizar documentos | | Documentos do sócio aparecem no representante legal | Upload feito pela rota direta ou token emitido sem `legalRepresentativeId` | Emita o token com o id do sócio e reenvie | | `404` com "Merchant não encontrado" na listagem | A subconta não pertence à master autenticada | Confira o `merchantId` e a chave usada | | Link do documento não abre | URL assinada expirou (1 hora) | Consulte a listagem de novo | ## Perguntas frequentes > [accordion] Preciso usar o token se a empresa tem um só sócio? > > Não. Com um único representante, o upload direto em `POST /v1/submerchants/{id}/document` resolve. O token é útil quando há sócios adicionais ou quando você quer receber os arquivos direto do navegador, sem passar pelo seu servidor. > [accordion] Os documentos da empresa precisam de token por sócio? > > Não. `cnpj_card`, `social_contract` e `irs_letter` valem para a subconta inteira e podem ser enviados por qualquer uma das duas rotas, com ou sem `legalRepresentativeId`. > [accordion] Posso usar o mesmo token para dois sócios? > > Não. O sócio vem de dentro do token, e o token vale para um único envio. Emita um token para cada sócio e para cada envio. > [accordion] Posso informar a subconta ou o sócio no corpo do upload? > > Não. Em `POST /v1/document-uploads`, a subconta e o sócio vêm sempre do token, nunca do corpo. > [accordion] O token expõe a minha chave secreta? > > Não. O token é emitido pelo seu servidor com a chave secreta, mas só serve para enviar documentos daquela subconta (e daquele sócio) por 5 minutos. ## Como testar No [roteiro de homologação](/homologacao/roteiro), o cenário **FC-02** pede a evidência de cada upload (tipo enviado e resposta). Se a sua integração usa sócios adicionais, inclua também: * a criação com `additionalRepresentatives` e a resposta com `legalRepresentatives[]`; * a emissão do token com `legalRepresentativeId` e o upload correspondente; * a listagem com `include=documents` mostrando os documentos de cada sócio. ## Veja também > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Cadastro completo e status de aprovação. > [card] [Criar token de upload](/referencia/fast-connect/criar-token-upload) > > Referência da rota do token. > [card] [Enviar documentos com token](/referencia/fast-connect/enviar-documentos-com-token) > > Referência do upload com token. > [card] [Listar representantes](/referencia/fast-connect/listar-representantes) > > Referência da listagem de sócios e documentos. # Split de pagamentos Source: https://docs.fastpaybrasil.com/guias/fast-connect/split Divida o valor de cada venda entre a conta master e as subcontas do seu grupo Connect, por regra padrão da conta ou por cobrança via API, e saiba quando cada parte é repassada. O split divide automaticamente o valor de uma venda entre contas do mesmo [grupo Connect](/glossario) (a conta master e as subcontas dela). A plataforma recebe a comissão dela, o vendedor recebe a parte dele, e um parceiro pode receber uma fatia, tudo na mesma cobrança e sem transferências manuais depois da venda. ## Quando usar | Situação | Como o split ajuda | | - | - | | Plataforma que cobra comissão sobre as vendas dos clientes | A subconta vende e uma parte de cada venda vai para a conta master | | Marketplace com produto de um vendedor e frete ou serviço de outro | A venda é dividida entre duas subcontas do mesmo grupo | | Programa de afiliados ou indicação dentro do grupo | Uma subconta recebe um percentual das vendas de outra | | Conta master que vende e repassa parte a um parceiro | A master origina a cobrança e destina um percentual à subconta do parceiro | Não use o split para dividir valores com empresas fora do seu grupo Connect: todas as contas participantes precisam estar no mesmo grupo. Para cadastrar um novo participante, crie uma subconta ([Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc)). > [!WARNING] > > Para PSPs, o split é obrigatório: toda transação de PSP precisa ter split entre a conta master (PSP) e a subconta (lojista), e split de 100% para o PSP não é permitido. Veja as [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). ## Como funciona O desenho abaixo mostra como o valor de uma venda é dividido, usando o exemplo "Dois recebedores" desta página: a plataforma fica com 5% do líquido, o parceiro com 10% e o vendedor com o restante. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB ORIG["Subconta do vendedor
originadora da venda"]:::lojista API["Finvia API"]:::finvia Q{"A cobrança traz
o campo split?"}:::decisao SAPI["Vale o split enviado
só para esta cobrança"]:::neutro SPAD["Vale a regra padrão
da conta ou da master"]:::neutro C(["Comprador"]):::comprador BRUTO["Valor bruto da venda"]:::neutro LIQ["Valor líquido
base do split"]:::alerta MASTER["Conta master
plataforma · 5%"]:::lojista PARC["Subconta do parceiro
entrega · 10%"]:::lojista VEND["Subconta do vendedor
restante · 85%"]:::lojista ORIG -->|"1. POST /v1/charges
com a chave dele"| API API --> Q Q -->|"sim"| SAPI Q -->|"não"| SPAD C -->|"2. paga"| BRUTO SAPI --> BRUTO SPAD --> BRUTO BRUTO -->|"3. menos a taxa da Finvia
fixa + percentual"| LIQ LIQ ==>|"4. 5%"| MASTER LIQ ==>|"4. 10%"| PARC LIQ ==>|"4. o que sobra"| VEND classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` O valor de cada participante é calculado na criação da cobrança e dividido igualmente entre as parcelas. O vendedor não entra na lista `split`: como originador, ele fica com o que sobra. **1. Defina quem origina a venda** O [originador](/glossario) é a conta cuja chave secreta cria a cobrança. Em um marketplace, normalmente é a subconta do vendedor. **2. Defina os recebedores e percentuais** Cada recebedor é um `merchantId` com um `percentage` entre `0.01` e `100`. A soma não pode passar de 100%. **3. Crie a cobrança** Com regra de split padrão configurada na conta, basta criar a cobrança. Para uma divisão específica daquela venda, envie o campo `split` em `POST /v1/charges`. **4. O valor de cada participante é calculado** Na criação da cobrança, a Finvia desconta a taxa transacional (fixa + percentual) do [valor bruto](/glossario). Sobre o [valor líquido](/glossario) que sobra, cada recebedor fica com o percentual dele. O restante fica com o originador. O valor de cada participante é dividido igualmente entre as parcelas. **5. Repasse na liquidação** Cada parte é repassada parcela a parcela, quando o recebível do originador é [liquidado](/glossario): no cartão, a cada 30 dias por parcela; no Pix, logo após a confirmação do pagamento. Veja a seção "Liquidação e repasse", abaixo. ## Regras de negócio | Regra | Detalhe | | - | - | | Soma dos percentuais | Não pode passar de 100% | | Restante | Se a soma for menor que 100%, o que sobra fica com o originador da venda | | Grupo | Todas as contas participantes precisam pertencer ao mesmo grupo Connect | | Limites por recebedor | `percentage` mínimo `0.01` e máximo `100` | | Base de cálculo | Por padrão, o percentual incide sobre o valor **líquido**, depois da taxa transacional da Finvia. Calcular sobre o valor bruto é uma configuração de conta, sob consulta | | Autenticação | A cobrança é criada com a chave secreta da conta originadora | | Prioridade | O split enviado na API vale só para aquela cobrança e prevalece sobre a regra padrão da conta | | Sem `split` na cobrança | Vale a regra padrão da conta para aquela moeda e método. Subconta sem regra própria usa a regra padrão da master | | Repasse | Parcela a parcela, na liquidação do recebível do originador: cartão em D+30, D+60...; Pix no mesmo dia, logo após a confirmação | | PSP | Toda transação de PSP precisa de split entre a master (PSP) e a subconta (lojista). Split de 100% para o PSP não é permitido | | Assinaturas | As cobranças recorrentes de assinatura não recebem split | ### Relações permitidas | Originador | Recebedor | | - | - | | Conta master | Subconta | | Subconta | Conta master | | Subconta | Subconta do mesmo grupo | > [!WARNING] > > O percentual é aplicado sobre o valor **líquido**, que é o valor da venda menos as taxas da Finvia. Se a sua plataforma cobra 2% sobre o valor bruto e você envia `percentage: 2`, recebe menos do que espera. Calcule o percentual correto com a fórmula de [Cálculo de split](/guias/fast-connect/calculo-split). > [!WARNING] > > Para que a venda fique vinculada à subconta que vendeu, crie a cobrança com a **chave secreta da subconta originadora**, obtida em `GET /v1/submerchants/{id}/api-keys`. Se a cobrança for criada com a chave da master, a master é a originadora. ## Split padrão da conta No [painel da Finvia](https://app.finvia.com.br), na gestão de subcontas, você configura a regra de split padrão: os participantes e o percentual de cada um. * A configuração vira o **padrão** daquela conta: todas as cobranças que ela originar sem o campo `split` seguem a regra. * A regra vale por moeda e por meio de pagamento (por exemplo, um percentual no Pix e outro no cartão). * Uma subconta sem regra própria usa a regra padrão definida pela master. > [!NOTE] > > **Para o negócio:** o split padrão é indicado quando a regra comercial é fixa por vendedor, como uma comissão contratual. A sua equipe configura uma vez e as vendas seguintes já saem divididas, mesmo que a integração não envie o campo `split`. ## Split por cobrança via API Envie o campo `split` no corpo de `POST /v1/charges`: | Campo | Tipo | Descrição | | - | - | - | | `split` | array | Lista de recebedores daquela cobrança | | `split[].merchantId` | string | `id` da conta que recebe a parte | | `split[].percentage` | number | Percentual destinado a essa conta. Mínimo `0.01`, máximo `100` | A configuração enviada pela API vale **somente para aquela cobrança** e prevalece sobre a regra padrão da conta. O split vale para cobranças criadas por `POST /v1/charges`; as cobranças recorrentes de assinatura não recebem split. **Em validação (V-64):** há um erro conhecido no split de cobranças com 3D Secure gerenciado. Até a correção, não combine split com 3DS gerenciado. > [!TIP] > > **Para o desenvolvedor:** use o split via API quando o percentual muda de venda para venda (por exemplo, comissão diferente por categoria de produto ou por campanha). Calcule o percentual no seu servidor, com as taxas reais da subconta, antes de criar a cobrança. ## Exemplos Os exemplos usam três contas do mesmo grupo Connect. Substitua pelos `id` reais. | Papel | `id` de exemplo | | - | - | | Conta master (plataforma) | `36OO3bcGjhPjjF3tzrqOGcmQuKo` | | Subconta do vendedor | `2vorkDcXyvzifL63YX09S9VqcnI` | | Subconta do parceiro | `2vorkEaaaBbbCccDddEeeFffGgg` | A variável `SUBCONTA_SECRET_KEY` guarda a chave secreta da subconta do vendedor, e `FINVIA_API_KEY` guarda a chave secreta da conta master. > [tab] Comissão da plataforma > > A subconta do vendedor vende um produto de R\$ 100,00 por Pix e a plataforma (conta master, `36OO3bcGjhPjjF3tzrqOGcmQuKo`) recebe a comissão. A plataforma cobra 2% sobre o bruto. As taxas deste exemplo são ilustrativas: Pix com 1,5% e sem taxa fixa. O líquido é R\$ 98,50 e o percentual sobre o líquido fica em `2.0305`, que entrega R\$ 2,00 à plataforma (veja a fórmula em [Cálculo de split](/guias/fast-connect/calculo-split)). Na sua integração, use as taxas reais da subconta. > > ```bash theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ > -u "$SUBCONTA_SECRET_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "amount": 100, > "currency": "BRL", > "customer": { > "name": "Joao Silva", > "email": "joao@email.com", > "document": { "type": "cpf", "id": "52998224725" } > }, > "paymentMethod": { "type": "pix", "expirationInSeconds": 3600 }, > "items": [ > { "title": "Curso de fotografia", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 100, "quantity": 1 } > ], > "split": [ > { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 2.0305 } > ], > "postbackUrl": "https://meusite.com.br/webhooks/finvia" > }' > ``` > [tab] Dois recebedores > > Venda de R\$ 450,00 em 3x no cartão. A subconta do vendedor (`2vorkDcXyvzifL63YX09S9VqcnI`) origina a venda com a chave dela. A plataforma (conta master, `36OO3bcGjhPjjF3tzrqOGcmQuKo`) recebe 5% do líquido e o parceiro de entrega (subconta `2vorkEaaaBbbCccDddEeeFffGgg`) recebe 10% do líquido. A soma é 15%, e os 85% restantes ficam com o vendedor, que não aparece na lista `split` porque é o originador. > > ```bash theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ > -u "$SUBCONTA_SECRET_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "amount": 450, > "currency": "BRL", > "customer": { > "name": "Maria Souza", > "email": "maria@email.com", > "document": { "type": "cpf", "id": "52998224725" } > }, > "paymentMethod": { > "type": "credit_card", > "number": "1111222233334444", > "holderName": "MARIA SOUZA", > "expirationMonth": "10", > "expirationYear": "2028", > "cvv": "123", > "installments": 3 > }, > "items": [ > { "title": "Luminária de mesa", "type": "physical", "description": "Luminária articulada", "unit_price": 450, "quantity": 1 } > ], > "shippingAddress": { > "postalCode": "01310100", > "addressLine1": "Av. Paulista, 1000", > "addressLine2": "Apto 51", > "neighborhood": "Bela Vista", > "city": "São Paulo", > "state": "SP", > "country": "BRA" > }, > "split": [ > { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 5 }, > { "merchantId": "2vorkEaaaBbbCccDddEeeFffGgg", "percentage": 10 } > ] > }' > ``` > [tab] Subconta para subconta > > Um professor (subconta do vendedor, `2vorkDcXyvzifL63YX09S9VqcnI`, originadora) vende uma aula de R\$ 200,00 e repassa 30% do líquido ao estúdio que hospeda a aula (subconta do parceiro, `2vorkEaaaBbbCccDddEeeFffGgg`). A conta master não participa desta divisão. > > ```bash theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ > -u "$SUBCONTA_SECRET_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "amount": 200, > "currency": "BRL", > "customer": { "name": "Ana Lima", "email": "ana@email.com" }, > "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, > "items": [ > { "title": "Aula particular de violão", "type": "digital", "description": "Aula online de 1 hora", "unit_price": 200, "quantity": 1 } > ], > "split": [ > { "merchantId": "2vorkEaaaBbbCccDddEeeFffGgg", "percentage": 30 } > ] > }' > ``` > [tab] Master para subconta > > A conta master vende diretamente e destina 15% do líquido à subconta do parceiro (`2vorkEaaaBbbCccDddEeeFffGgg`). Aqui a cobrança é criada com a chave secreta da master. > > ```bash theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ > -u "$FINVIA_API_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "amount": 120, > "currency": "BRL", > "customer": { "name": "Joao Silva", "email": "joao@email.com" }, > "paymentMethod": { "type": "pix", "expirationInDays": 1 }, > "items": [ > { "title": "Ingresso de workshop", "type": "digital", "description": "Workshop de marketing digital", "unit_price": 120, "quantity": 1 } > ], > "split": [ > { "merchantId": "2vorkEaaaBbbCccDddEeeFffGgg", "percentage": 15 } > ] > }' > ``` ### Exemplo em Node.js ```javascript Node.js theme={null} async function criarVendaComComissao({ chaveSubconta, valor, percentualSplit, contaComissao, pedido }) { const credentials = Buffer.from(`${chaveSubconta}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: valor, currency: 'BRL', customer: pedido.cliente, paymentMethod: { type: 'pix', expirationInSeconds: 3600 }, items: pedido.itens, metadata: { orderId: pedido.id }, split: [{ merchantId: contaComissao, percentage: percentualSplit }], }), }); return response.json(); } ``` ## Split em Pix e em cartão parcelado O campo `split` é o mesmo para Pix e para cartão. A diferença está nas taxas: cada método, bandeira e número de parcelas pode ter uma taxa diferente, e isso muda o valor líquido. Como o split incide sobre o líquido, o mesmo percentual entrega valores diferentes em uma venda Pix e em uma venda em 6x de mesmo valor bruto. Se a sua comissão é definida sobre o valor bruto, calcule o percentual para cada combinação de método e parcelas a partir das taxas reais da subconta ([Taxas da subconta](/guias/fast-connect/taxas) e [Cálculo de split](/guias/fast-connect/calculo-split)). ## Liquidação e repasse O valor de cada participante é calculado na criação da cobrança e repassado a cada parcela, quando o recebível do originador é liquidado: no cartão, a cada 30 dias por parcela (D+30, D+60...); no Pix, logo após a confirmação do pagamento. O repasse sai do saldo disponível do originador e entra no saldo disponível do recebedor. Se o originador antecipar, o repasse acontece na antecipação e é calculado sobre o valor já descontada a taxa de antecipação. A parte correspondente à reserva financeira do originador é repassada quando a reserva é liberada. O desenho abaixo mostra quando a parte do recebedor sai do saldo do originador e chega ao saldo dele, no Pix, no cartão parcelado e na antecipação. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB PAGA(["Cobrança paga
partes já calculadas"]):::ok ALIB["Saldo a liberar
do originador
recebedor ainda não vê"]:::alerta Q{"Quando o recebível
do originador liquida?"}:::decisao PIX["Pix
no mesmo dia, logo
após a confirmação"]:::neutro CARD["Cartão parcelado
parcela a cada 30 dias
1ª D+30 · 2ª D+60..."]:::neutro ANT["Antecipação: na hora
com base líquida, desconta
a taxa de antecipação"]:::alerta REP["Repasse
sai do saldo disponível
do originador"]:::finvia REC(["Saldo disponível
do recebedor"]):::ok PAGA --> ALIB ALIB --> Q Q -->|"Pix"| PIX Q -->|"cartão"| CARD Q -.->|"originador antecipa"| ANT PIX -->|"parte inteira"| REP CARD -->|"parte de cada
parcela"| REP ANT -->|"parte recalculada"| REP REP ==> REC classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 ``` Retenção do recebível pela Finvia, reserva financeira, bloqueio de saldo do recebedor e estorno mudam esse caminho como descrito na tabela a seguir. | Situação | O que acontece com o split | | - | - | | Cartão de crédito | Cada parcela é liberada 30 dias corridos depois da criação da cobrança: 1ª em D+30, 2ª em D+60 e assim por diante | | Pix | Liberação no mesmo dia, logo após a confirmação do pagamento | | Antes da liquidação | O valor inteiro fica no saldo a liberar do originador. O recebedor ainda não vê nada no saldo | | Recebível do originador retido pela Finvia | A liquidação e o repasse ficam suspensos até a liberação | | Recebedor com bloqueio de saldo | O crédito entra como saldo bloqueado | | Reserva financeira do originador | A fração do split que corresponde à parte reservada só é repassada quando a reserva daquele recebível é liberada pela Finvia (padrão de 90 dias). O restante é repassado na liquidação | | Antecipação pelo originador | Só o originador antecipa; o recebedor não antecipa a parte do split. Na antecipação, a parte do split é repassada na hora. Com base líquida (o padrão), o split é recalculado sobre o valor já descontada a taxa de antecipação, ou seja, o recebedor arca proporcionalmente com essa taxa | | Estorno depois do repasse | A parte já repassada é debitada do saldo do recebedor e devolvida ao originador | > [!NOTE] > > **Para o negócio:** duas opções são configuradas pela Finvia, **sob consulta**: calcular o split sobre o valor bruto (com base bruta, a antecipação não muda o valor do split) e a conta master absorver a taxa de antecipação das subcontas. Fale com o seu contato comercial se precisar de alguma delas. ## Consulte os valores divididos Depois da venda, consulte a cobrança em [`GET /v1/charges/{id}`](/referencia/cobrancas/consultar). A resposta traz a lista `splits`, um item por recebedor. Ela não aparece na listagem de cobranças nem na resposta de criação. ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/charges/2v2TGGb4NHTQWCiMmnelz2WVOZP" \ -u "$SUBCONTA_SECRET_KEY:" ``` | Campo de `splits[]` | Significado | | - | - | | `id` | Id do registro de split | | `destinyMerchantId` | Conta recebedora (o `merchantId` enviado em `split[]`) | | `destinyMerchantName` | Nome fantasia da conta recebedora | | `splitPercentage` | Percentual, como texto decimal (ex.: `"30.00000000"`). Converta para número | | `splitAmount` | Valor exibido para o recebedor, número com 2 casas (truncado). Veja abaixo | | `referenceAmount` | Base de cálculo: `net` (valor líquido, o padrão) ou `gross` (valor bruto) | No POST o campo é `split` (singular), com `merchantId` e `percentage`. Na consulta é `splits` (plural), com os nomes acima. Se a cobrança foi criada sem `split`, `splits` vem preenchido com a regra padrão da conta. O que `splitAmount` mostra com base `net`: * **Enquanto há parcelas a liquidar e nenhuma antecipação concluída:** uma simulação do valor que o recebedor teria se o originador antecipasse, já descontada a taxa de antecipação estimada. Não é o valor que será repassado. * **Depois que as parcelas liquidam sem antecipação:** o percentual sobre o valor líquido, sem desconto de antecipação. * **Depois de uma antecipação concluída:** o valor efetivamente destinado, recalculado sobre o valor antecipado. Com base `gross`, `splitAmount` é sempre o percentual × valor bruto. O split pode aparecer também em cobrança recusada, mas o repasse só acontece quando a cobrança é paga. Para acompanhar o total recebido por split em cada subconta, `GET /v1/submerchants/{id}` traz o objeto `metrics`, com `splitBalance` (total recebido por split, em reais) e `splitRate` (percentual médio de split aplicado à subconta). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Cobrança rejeitada com erro de validação | `percentage` igual a 0, acima de 100 ou soma dos percentuais acima de 100% | Envie cada percentual entre `0.01` e `100` e confira a soma | | Cobrança rejeitada | `merchantId` inexistente ou fora do seu grupo Connect | Use o `id` de uma conta do mesmo grupo | | Recebedor ficou com menos do que o esperado | Percentual calculado sobre o bruto, mas aplicado sobre o líquido | Recalcule com a fórmula de [Cálculo de split](/guias/fast-connect/calculo-split) | | Venda não aparece vinculada à subconta | Cobrança criada com a chave da master | Use a chave secreta da subconta originadora | | Venda saiu com a divisão configurada no painel | O campo `split` não foi enviado na cobrança, então valeu a regra padrão da conta (ou da master) | Envie `split` na cobrança. O split da API prevalece sobre o padrão | | `splitAmount` menor que percentual × líquido | Enquanto as parcelas não liquidam, o valor exibido simula uma antecipação | Use `splitPercentage` e `referenceAmount` para conferir. O valor final aparece depois da liquidação | | Assinatura sem split | As cobranças recorrentes de assinatura não recebem split | Use cobranças avulsas em `POST /v1/charges` quando precisar dividir o valor | | Valores com diferença de centavos | Arredondamento do percentual | Mantenha as casas decimais do percentual e arredonde só o valor em reais, no fechamento ([Cálculo de split](/guias/fast-connect/calculo-split)) | ## Perguntas frequentes > [accordion] Se eu não enviar split na cobrança, o que acontece? > > Vale a regra padrão da conta originadora para aquela moeda e método. Uma subconta sem regra própria usa a regra padrão da master. Sem nenhuma regra, a venda inteira (líquida de taxas) fica com o originador. > [accordion] Posso mandar 100% para outra conta? > > Tecnicamente, o máximo por recebedor é `100`, e a soma não pode passar de 100%. Para PSPs, a regra é outra: split de 100% para o PSP não é permitido, e toda transação precisa dividir o valor entre a master e a subconta do lojista. > [accordion] O split da API substitui a regra padrão ou soma com ela? > > Substitui. A configuração enviada na cobrança vale só para ela e prevalece sobre a regra padrão. > [accordion] Quando o recebedor vê o dinheiro? > > Na liquidação de cada parcela do originador: no cartão, em D+30 para a 1ª parcela, D+60 para a 2ª e assim por diante; no Pix, no mesmo dia, logo após a confirmação. Se o originador antecipar, o repasse acontece na antecipação. > [accordion] Quem paga as taxas da Finvia na venda com split? > > Com a base líquida (o padrão), a taxa transacional é descontada antes da divisão, e todos os participantes recebem o percentual deles sobre o que sobra. Se o originador antecipar, a taxa de antecipação também reduz a base. A base bruta e a opção de a master absorver a taxa de antecipação das subcontas existem sob consulta. ## Como testar Cenários do [roteiro de homologação](/homologacao/roteiro), seção de cobrança com split: | Código | O que comprovar | | - | - | | SPL-01 | Cobrança com split para 1 recebedor (ex.: 30%), aprovada, e `GET /v1/charges/{id}` mostrando `splits` com `destinyMerchantId` e `splitPercentage` | | SPL-02 | Split para 2 ou mais recebedores somando até 100% | | SPL-03 | Percentual inválido (0, acima de 100 ou soma inconsistente) rejeitado pela API | | SPL-04 | `merchantId` inexistente ou fora do grupo rejeitado pela API | | SPL-05 | `splitPercentage` e `splitAmount` coerentes com a base (`referenceAmount`). Antes da liquidação, `splitAmount` pode ser menor por causa da simulação de antecipação | | SPL-06 | Split em Pix e em cartão parcelado, se usar os dois | | FC-05, FC-06 | Cobrança criada com a chave da subconta e cobrança com split entre subcontas do grupo | ## Veja também > [card] [Cálculo de split](/guias/fast-connect/calculo-split) > > Como transformar uma comissão sobre o bruto no percentual correto. > [card] [Taxas da subconta](/guias/fast-connect/taxas) > > De onde vêm as taxas que definem o valor líquido. > [card] [Criar cobrança](/referencia/cobrancas/criar) > > Referência completa, incluindo o campo `split`. > [card] [Marketplace e PSP](/casos-de-uso/marketplace-psp) > > Caso de uso completo com subcontas e split. # Subcontas e KYC Source: https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc Cadastre subcontas, envie os documentos para análise, acompanhe o status do credenciamento e obtenha as chaves de API de cada subconta. Cada vendedor, lojista ou cliente que opera dentro da sua estrutura Connect precisa de uma **subconta** (SubMerchant). O ciclo tem três partes: você cadastra a empresa, envia os documentos para a análise de KYC (a verificação da identidade das pessoas e dos dados da empresa) e, quando a Finvia aprova, a subconta recebe as próprias chaves de API para vender. > [!NOTE] > > **Para o negócio:** a subconta só vende depois de aprovada. Monte o formulário de cadastro da sua plataforma já com todos os campos e documentos listados nesta página. Dados faltando ou documentos ilegíveis levam a pedidos de correção (status `correcting`), e o cadastro volta para a fila de análise. ## Quando usar * **Entrada de um novo vendedor no marketplace**: o vendedor preenche o cadastro na sua plataforma e a sua aplicação cria a subconta pela API. * **Credenciamento de lojistas por um PSP**: cada lojista credenciado vira uma subconta com dados bancários e documentos próprios. * **Migração de uma base de clientes** para o Connect: a criação em lote é feita chamando a rota uma vez por empresa. Se a empresa tem mais de um sócio e você precisa enviar documentos de cada um, veja também [Sócios e documentos](/guias/fast-connect/socios-e-documentos). Os documentos exigidos, o prazo médio da análise, os motivos de recusa e os ramos (MCCs) não aceitos estão em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). ## Como funciona A sequência abaixo mostra o credenciamento de uma subconta, do cadastro até as chaves de API. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(243,245,248) Sua aplicação participant S as Seu servidor (master) participant R as URL de aviso (postbackUrl) end box rgb(234,243,255) Finvia participant F as Finvia API participant K as Análise Finvia (KYC) end Note over S: Pré-valida dados e documentos do lojista S->>F: POST /v1/submerchants (chave da master) F-->>S: 201 · id · legalRepresentatives (nasce pending) S->>F: POST /v1/submerchants/{id}/document (multipart) F-->>S: 201 sem corpo F->>K: Cadastro e documentos entram na análise alt Correção pedida K-)R: Aviso correcting · rejectionReason Note over S,K: Correção feita no painel Finvia. O cadastro volta para pending, sem aviso else Documentos conferidos e aprovação final K-)R: Aviso pre_approved K-)R: Aviso active S->>F: GET /v1/submerchants/{id} F-->>S: status active · approvedAt S->>F: GET /v1/submerchants/{id}/api-keys F-->>S: publicKey e secretKey else Reprovada K-)R: Aviso rejected · rejectionReason end ``` **1. Pré-valide o lojista** Confira do seu lado os dados e documentos do lojista antes de enviar, como pedem as [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). **2. Crie a subconta** `POST /v1/submerchants` com a chave secreta da conta master. A resposta traz o `id` da subconta e a lista `legalRepresentatives`. A subconta começa com status `pending`. **3. Envie os documentos** `POST /v1/submerchants/{id}/document` em `multipart/form-data`, um arquivo por tipo de documento. **4. Acompanhe a análise** A Finvia analisa o cadastro. Você acompanha pelo aviso de mudança de status e pela consulta `GET /v1/submerchants/{id}`. **5. Corrija, se pedido** Se o status for para `correcting`, o motivo vem no aviso. Depois que a correção é reenviada, o cadastro volta para a análise. **6. Obtenha as chaves** Com o status `active`, busque as chaves em `GET /v1/submerchants/{id}/api-keys` e guarde no seu cofre de segredos. ## Regras de negócio | Regra | Detalhe | | - | - | | Quem cria | A conta master, com a chave secreta dela | | Cópia de taxas | Na criação, a subconta recebe uma cópia das taxas, permissões e configurações da master. Depois, as taxas são independentes | | CNPJ único | O mesmo CNPJ não pode ser cadastrado em duas subcontas da mesma master, em qualquer status, nem repetir o CNPJ da master (`409`) | | Representante legal | `legalRepresentative` é obrigatório e é sempre o representante legal da empresa | | Sócios adicionais | Opcionais, em `additionalRepresentatives`, com o mesmo formato do representante legal | | Acesso ao painel | `canAccessDashboard` é obrigatório. Se for `true`, o objeto `user` passa a ser obrigatório | | Descrição na fatura | `softDescriptor` tem no máximo 40 caracteres | | Documentos aceitos | JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF, até 50 MB por arquivo | | Upload após aprovação | Bloqueado. A API responde `422` | | Correção de cadastro | Feita pelo painel, na gestão de subcontas, não pela API | | Chaves | Obtidas pela master em `GET /v1/submerchants/{id}/api-keys`. Use-as para cobrar só com a subconta `active` | > [!WARNING] > > Com país `BRA`, o `companyTaxId`, o `idNumber` do representante legal e dos sócios (CPF) e o `bankAccount.recipientDocument` são **validados com dígitos verificadores**. Os números desta página são válidos só para teste de formato. Use os documentos reais da empresa e das pessoas. ## Dados exigidos na criação O corpo de `POST /v1/submerchants` é organizado em blocos. Todos os campos marcados como obrigatórios precisam estar presentes. ### Empresa | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `legalName` | string | Sim | Razão social | | `tradeName` | string | Sim | Nome fantasia | | `companyTaxId` | string | Sim | CNPJ da empresa, com ou sem máscara. Com país `BRA`, o dígito verificador é validado | | `website` | string (`uri`) | Sim | URL do lojista, onde estão os produtos ou serviços que serão vendidos | | `averageMonthlyRevenue` | number | Sim | Expectativa de faturamento médio mensal, em reais | | `averageOrderValue` | number | Sim | Ticket médio por pedido, em reais | | `productType` | string | Sim | Tipo de produto vendido: `digital`, `physical` ou `both` | | `contactEmail` | string | Sim | E-mail de contato da empresa | | `productDescription` | string | Sim | Descrição curta dos produtos ou serviços | | `softDescriptor` | string | Não | Nome que aparece na fatura do cartão do cliente. Máximo de 40 caracteres | | `address` | object | Sim | Endereço da empresa (veja a tabela abaixo) | | `phones` | array | Sim | Telefones da empresa. Cada item tem `type` (ex.: `mobile`) e `number`, os dois obrigatórios | | `postbackUrl` | string (`uri`) | Não | URL para receber o aviso quando o status da subconta mudar (veja [Status que geram aviso](#status-que-geram-aviso)) | > [!NOTE] > > **Para o negócio:** `website`, `averageMonthlyRevenue` e `averageOrderValue` são a URL do lojista, a expectativa de faturamento e o ticket médio que as [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento) exigem. `productType` precisa refletir o que o vendedor realmente vende; se ele vende os dois tipos, cadastre `both`. #### Endereço | Campo | Obrigatório | Descrição | | - | - | - | | `addressLine1` | Sim | Logradouro e número, separados por vírgula, com o número no fim. Ex.: `Av. Paulista, 1000`. O número é extraído desse formato para o credenciamento nas adquirentes; sem vírgula e número, pode ir como "S/N" | | `addressLine2` | Não | Complemento: apartamento, sala, bloco, andar. Ex.: `Sala 12` | | `referencePoint` | Não | Ponto de referência, até 255 caracteres. Só é gravado no endereço da empresa | | `neighborhood` | Sim | Bairro. Obrigatório quando o país é `BRA` | | `city` | Sim | Cidade | | `state` | Sim | Estado. Com país `BRA`, precisa ser uma UF válida (ex.: `SP`) | | `country` | Sim | País em ISO 3166-1 alpha-3, em maiúsculas. Ex.: `BRA`. `BR` é recusado com `400` | | `postalCode` | Sim | CEP. Com país `BRA`, 8 dígitos. Ex.: `01310100` | ### Representante legal Objeto `legalRepresentative`, obrigatório. | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `fullName` | string | Sim | Nome completo | | `idNumber` | string | Sim | Número do documento. Precisa ser um CPF válido quando `issuingCountry` é `BRA` ou não é enviado | | `idType` | string | Não | Tipo do documento de identificação (ex.: `cpf`) | | `issuingCountry` | string | Não | País emissor do documento, em ISO 3166-1 alpha-3 (ex.: `BRA`) | | `dateOfBirth` | string (`date`) | Sim | Data de nascimento, no formato `AAAA-MM-DD` | | `nationality` | string | Sim | Nacionalidade, em texto livre (ex.: `Brasileira`) | | `email` | string | Sim | E-mail | | `motherName` | string | Sim | Nome da mãe | | `gender` | string | Sim | `M` ou `F` | | `phones` | array | Sim | Telefones, cada um com `type` e `number` | | `address` | object | Não | Endereço próprio da pessoa, com os mesmos campos do endereço da empresa (sem `referencePoint`, que não é gravado aqui). Se omitido, o representante usa o endereço da empresa | ### Sócios adicionais Array `additionalRepresentatives`, opcional. Cada item tem o mesmo formato do representante legal. O `idNumber` do sócio é o CPF, validado com dígitos verificadores. O envio dos documentos de cada sócio está em [Sócios e documentos](/guias/fast-connect/socios-e-documentos). ### Conta bancária Objeto `bankAccount`, obrigatório. | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `bankCode` | string | Sim | Código do banco (ex.: `001`) | | `agencyCode` | string | Sim | Agência | | `accountNumber` | string | Sim | Número da conta | | `accountDigit` | string | Sim | Dígito da conta | | `accountType` | string | Sim | `checking` (corrente) ou `savings` (poupança) | | `bankName` | string | Sim | Nome do banco | | `recipientName` | string | Sim | Nome do titular da conta | | `recipientDocument` | string | Sim | CPF ou CNPJ do titular, validado com dígitos verificadores | | `routingNumber` | string | Não | Routing number, para contas dos Estados Unidos | ### Acesso ao painel | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `canAccessDashboard` | boolean | Sim | Define se a subconta pode acessar o painel | | `user` | object | Quando `canAccessDashboard` é `true` | Usuário do painel: `fullName`, `email` e `phone`, todos obrigatórios. O `phone` vai no formato internacional E.164, por exemplo `+5511987654321`. E-mail já cadastrado devolve `400` `Email already registered` | ## Status do credenciamento A subconta passa por estes status ao longo da vida: | Status | Significado | O que fazer | | - | - | - | | `pending` | Cadastro recebido, em análise | Envie os documentos e aguarde | | `correcting` | A Finvia pediu correção de dados ou documentos. O motivo vem no aviso, em `rejectionReason` | Corrija e reenvie | | `pre_approved` | Documentos obrigatórios conferidos. A subconta está sendo credenciada nas adquirentes e aguarda a aprovação final | Aguarde | | `active` | Aprovada e apta a transacionar | Busque as chaves e libere as vendas | | `rejected` | Reprovada | Avise o vendedor. A subconta não opera | | `blocked` | Bloqueada | Fale com a Finvia | | `inactive` | Inativada | Nenhuma operação | O caminho comum é `pending`, depois `pre_approved`, depois `active`. A aprovação final só parte de `pre_approved`. O pedido de correção (`correcting`) só acontece a partir de `pending` ou `pre_approved`; depois que a correção é reenviada, a subconta volta para a análise. Uma conta `active` pode ser bloqueada (`blocked`) e desbloqueada, ou inativada (`inactive`). O desenho abaixo mostra todas as mudanças de status possíveis. As setas pontilhadas são as mudanças que não geram aviso. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB S(["POST /v1/submerchants"]):::neutro PEN["pending
em análise"]:::alerta COR["correcting
correção pedida"]:::alerta PRE["pre_approved
credenciando nas adquirentes"]:::alerta ACT["active
apta a vender"]:::ok REJ["rejected
reprovada"]:::erro BLK["blocked
bloqueada"]:::erro INA["inactive
inativada"]:::neutro S -.->|"criação"| PEN PEN -->|"documentos conferidos"| PRE PEN -->|"pede correção"| COR PRE -->|"pede correção"| COR COR -.->|"correção reenviada
sem aviso"| PEN PRE ==>|"aprovação final"| ACT PEN -->|"reprovação"| REJ PRE -->|"reprovação"| REJ COR -->|"reprovação"| REJ ACT -->|"bloqueio"| BLK BLK -->|"desbloqueio"| ACT ACT -.->|"inativação
sem aviso"| INA classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ### Status que geram aviso Nem toda mudança gera notificação. Só estas cinco transições disparam o aviso de mudança de status: | Status | Traz `rejectionReason`? | | - | - | | `pre_approved` | Não | | `correcting` | Sim | | `active` (aprovação e também desbloqueio) | Não | | `rejected` | Sim | | `blocked` | Não | `pending` (inclusive a volta para análise depois de uma correção) e a inativação (`inactive`) **não** geram aviso. Para esses casos, consulte a subconta. O aviso vai para o `postbackUrl` informado na criação da subconta. A URL fica salva nas configurações da subconta; para alterá-la depois, fale com o suporte. Sem `postbackUrl`, a subconta usa a URL de aviso de status da conta master, se a master tiver uma. O aviso não vai aos endpoints de webhook do painel nem ao `postbackUrl` das cobranças. O aviso é um `POST` sem envelope, com campos em camelCase: ```json theme={null} { "merchantId": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "correcting", "date": "2026-01-13T12:39:48Z", "rejectionReason": "Documento de identidade ilegível. Reenvie o RG ou CNH com qualidade adequada." } ``` O campo `date` é a data de referência do status e pode ser diferente do momento exato da mudança. Em `active`, por exemplo, é a data da aprovação, mesmo num desbloqueio. > [!TIP] > > **Para o desenvolvedor:** responda o aviso com um status 2xx em até 10 segundos; qualquer outro resultado conta como falha de entrega. Use `merchantId` + `status` + `date` como chave para ignorar avisos repetidos e confirme o status atual com `GET /v1/submerchants/{id}`. Detalhes em [Webhooks de conta](/guias/webhooks/conta). ## Passo a passo ### 1. Crie a subconta ```http REST (JSON) theme={null} POST /v1/submerchants HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "legalName": "Ateliê Lima Cerâmicas LTDA", "tradeName": "Ateliê Lima", "companyTaxId": "11222333000181", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "both", "contactEmail": "contato@email.com", "productDescription": "Peças de cerâmica artesanal e aulas online de modelagem.", "softDescriptor": "ATELIELIMA", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "idNumber": "52998224725", "idType": "cpf", "issuingCountry": "BRA", "dateOfBirth": "1985-04-20", "nationality": "Brasileira", "email": "ana@email.com", "motherName": "Maria Souza Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "Ateliê Lima Cerâmicas LTDA", "recipientDocument": "11222333000181" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/subcontas", "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana@email.com", "phone": "+5511987654321" } } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "legalName": "Ateliê Lima Cerâmicas LTDA", "tradeName": "Ateliê Lima", "companyTaxId": "11222333000181", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "both", "contactEmail": "contato@email.com", "productDescription": "Peças de cerâmica artesanal e aulas online de modelagem.", "softDescriptor": "ATELIELIMA", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "idNumber": "52998224725", "idType": "cpf", "issuingCountry": "BRA", "dateOfBirth": "1985-04-20", "nationality": "Brasileira", "email": "ana@email.com", "motherName": "Maria Souza Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "Ateliê Lima Cerâmicas LTDA", "recipientDocument": "11222333000181" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/subcontas", "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana@email.com", "phone": "+5511987654321" } }' ``` ```javascript Node.js theme={null} import { readFile } from 'node:fs/promises'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); // subconta.json: mesmo corpo do exemplo em cURL const dadosDaSubconta = JSON.parse(await readFile('./subconta.json', 'utf8')); const response = await fetch('https://api-global.fastpaybrasil.com/v1/submerchants', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify(dadosDaSubconta), }); const result = await response.json(); if (response.status === 201) { const { id, legalRepresentatives } = result; // guarde o id da subconta e os ids dos representantes console.log(id, legalRepresentatives); } else { console.error(response.status, result.message); // 400, 409 (CNPJ já cadastrado), 403... } ``` ```python Python theme={null} import os import requests payload = { "legalName": "Ateliê Lima Cerâmicas LTDA", "tradeName": "Ateliê Lima", "companyTaxId": "11222333000181", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "both", "contactEmail": "contato@email.com", "productDescription": "Peças de cerâmica artesanal e aulas online de modelagem.", "softDescriptor": "ATELIELIMA", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100", }, "phones": [ { "type": "mobile", "number": "+5511987654321", }, ], "legalRepresentative": { "fullName": "Ana Lima", "idNumber": "52998224725", "idType": "cpf", "issuingCountry": "BRA", "dateOfBirth": "1985-04-20", "nationality": "Brasileira", "email": "ana@email.com", "motherName": "Maria Souza Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321", }, ], }, "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "Ateliê Lima Cerâmicas LTDA", "recipientDocument": "11222333000181", }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/subcontas", "canAccessDashboard": True, "user": { "fullName": "Ana Lima", "email": "ana@email.com", "phone": "+5511987654321", }, } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/submerchants", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'Ateliê Lima Cerâmicas LTDA', 'tradeName' => 'Ateliê Lima', 'companyTaxId' => '11222333000181', 'website' => 'https://loja.exemplo.com.br', 'averageMonthlyRevenue' => 30000, 'averageOrderValue' => 150, 'productType' => 'both', 'contactEmail' => 'contato@email.com', 'productDescription' => 'Peças de cerâmica artesanal e aulas online de modelagem.', 'softDescriptor' => 'ATELIELIMA', 'address' => [ 'addressLine1' => 'Av. Paulista, 1000', 'addressLine2' => 'Sala 12', 'neighborhood' => 'Bela Vista', 'city' => 'São Paulo', 'state' => 'SP', 'country' => 'BRA', 'postalCode' => '01310100', ], 'phones' => [ [ 'type' => 'mobile', 'number' => '+5511987654321', ], ], 'legalRepresentative' => [ 'fullName' => 'Ana Lima', 'idNumber' => '52998224725', 'idType' => 'cpf', 'issuingCountry' => 'BRA', 'dateOfBirth' => '1985-04-20', 'nationality' => 'Brasileira', 'email' => 'ana@email.com', 'motherName' => 'Maria Souza Lima', 'gender' => 'F', 'phones' => [ [ 'type' => 'mobile', 'number' => '+5511987654321', ], ], ], 'bankAccount' => [ 'bankCode' => '001', 'agencyCode' => '1234', 'accountNumber' => '567890', 'accountDigit' => '0', 'accountType' => 'checking', 'bankName' => 'Banco do Brasil', 'recipientName' => 'Ateliê Lima Cerâmicas LTDA', 'recipientDocument' => '11222333000181', ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia/subcontas', 'canAccessDashboard' => true, 'user' => [ 'fullName' => 'Ana Lima', 'email' => 'ana@email.com', 'phone' => '+5511987654321', ], ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "legalName": "Ateliê Lima Cerâmicas LTDA", "tradeName": "Ateliê Lima", "companyTaxId": "11222333000181", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "both", "contactEmail": "contato@email.com", "productDescription": "Peças de cerâmica artesanal e aulas online de modelagem.", "softDescriptor": "ATELIELIMA", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "idNumber": "52998224725", "idType": "cpf", "issuingCountry": "BRA", "dateOfBirth": "1985-04-20", "nationality": "Brasileira", "email": "ana@email.com", "motherName": "Maria Souza Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "Ateliê Lima Cerâmicas LTDA", "recipientDocument": "11222333000181" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/subcontas", "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana@email.com", "phone": "+5511987654321" } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "legalName": "Ateliê Lima Cerâmicas LTDA", "tradeName": "Ateliê Lima", "companyTaxId": "11222333000181", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "both", "contactEmail": "contato@email.com", "productDescription": "Peças de cerâmica artesanal e aulas online de modelagem.", "softDescriptor": "ATELIELIMA", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "idNumber": "52998224725", "idType": "cpf", "issuingCountry": "BRA", "dateOfBirth": "1985-04-20", "nationality": "Brasileira", "email": "ana@email.com", "motherName": "Maria Souza Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "Ateliê Lima Cerâmicas LTDA", "recipientDocument": "11222333000181" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/subcontas", "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana@email.com", "phone": "+5511987654321" } } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "legalName": "Ateliê Lima Cerâmicas LTDA", "tradeName": "Ateliê Lima", "companyTaxId": "11222333000181", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "both", "contactEmail": "contato@email.com", "productDescription": "Peças de cerâmica artesanal e aulas online de modelagem.", "softDescriptor": "ATELIELIMA", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "idNumber": "52998224725", "idType": "cpf", "issuingCountry": "BRA", "dateOfBirth": "1985-04-20", "nationality": "Brasileira", "email": "ana@email.com", "motherName": "Maria Souza Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "Ateliê Lima Cerâmicas LTDA", "recipientDocument": "11222333000181" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/subcontas", "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana@email.com", "phone": "+5511987654321" } }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "legalName" => "Ateliê Lima Cerâmicas LTDA", "tradeName" => "Ateliê Lima", "companyTaxId" => "11222333000181", "website" => "https://loja.exemplo.com.br", "averageMonthlyRevenue" => 30000, "averageOrderValue" => 150, "productType" => "both", "contactEmail" => "contato@email.com", "productDescription" => "Peças de cerâmica artesanal e aulas online de modelagem.", "softDescriptor" => "ATELIELIMA", "address" => { "addressLine1" => "Av. Paulista, 1000", "addressLine2" => "Sala 12", "neighborhood" => "Bela Vista", "city" => "São Paulo", "state" => "SP", "country" => "BRA", "postalCode" => "01310100", }, "phones" => [ { "type" => "mobile", "number" => "+5511987654321", }, ], "legalRepresentative" => { "fullName" => "Ana Lima", "idNumber" => "52998224725", "idType" => "cpf", "issuingCountry" => "BRA", "dateOfBirth" => "1985-04-20", "nationality" => "Brasileira", "email" => "ana@email.com", "motherName" => "Maria Souza Lima", "gender" => "F", "phones" => [ { "type" => "mobile", "number" => "+5511987654321", }, ], }, "bankAccount" => { "bankCode" => "001", "agencyCode" => "1234", "accountNumber" => "567890", "accountDigit" => "0", "accountType" => "checking", "bankName" => "Banco do Brasil", "recipientName" => "Ateliê Lima Cerâmicas LTDA", "recipientDocument" => "11222333000181", }, "postbackUrl" => "https://meusite.com.br/webhooks/finvia/subcontas", "canAccessDashboard" => true, "user" => { "fullName" => "Ana Lima", "email" => "ana@email.com", "phone" => "+5511987654321", }, }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201`: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "legalRepresentatives": [ { "id": "2vorkEaaaBbbCccDddEeeFffGgg", "fullName": "Ana Lima", "isPrimary": true } ] } ``` Guarde o `id`: ele é usado em todas as chamadas seguintes da subconta, e é o `merchantId` dela no split e no saque. ### 2. Envie os documentos A rota `POST /v1/submerchants/{id}/document` recebe os arquivos em `multipart/form-data`. O nome de cada campo é o tipo do documento: | Campo | Documento | Vínculo | | - | - | - | | `social_contract` | Contrato social da empresa | Empresa | | `cnpj_card` | Cartão CNPJ | Empresa | | `responsible_document_front` | Documento de identidade do representante legal, frente | Representante legal | | `responsible_document_back` | Documento de identidade do representante legal, verso | Representante legal | | `selfie_with_document` | Selfie do representante legal segurando o documento | Representante legal | | `irs_letter` | IRS letter, usada no fluxo de cadastro de LLC (empresa dos Estados Unidos) | Empresa | Para uma empresa brasileira, o credenciamento pede contrato social, cartão CNPJ, documento do responsável frente e verso e selfie com documento; para MEI, cartão CNPJ e certificado de MEI. Não há campo próprio para o certificado de MEI: fale com o suporte para enviá-lo. A lista completa está em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). É preciso enviar pelo menos um arquivo por chamada, e você pode enviar todos de uma vez. ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/document" \ -u "$FINVIA_API_KEY:" \ -F "social_contract=@contrato-social.pdf" \ -F "cnpj_card=@cartao-cnpj.pdf" \ -F "responsible_document_front=@rg-frente.jpg" \ -F "responsible_document_back=@rg-verso.jpg" \ -F "selfie_with_document=@selfie-com-rg.jpg" ``` > [!TIP] > > **Para o desenvolvedor:** não defina o cabeçalho `Content-Type` manualmente em envios multipart. O cURL (com `-F`) e as bibliotecas HTTP montam o cabeçalho com o separador (`boundary`) correto. A resposta de sucesso é `201`, sem corpo. > [!NOTE] > > Esta rota vincula os documentos de pessoa sempre ao **representante legal**. Se a empresa tem só um representante, ela é tudo o que você precisa. Para documentos de sócios adicionais, ou para receber os arquivos direto do navegador do vendedor sem expor a sua chave, use o fluxo com token descrito em [Sócios e documentos](/guias/fast-connect/socios-e-documentos). ### 3. Consulte até `active` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI" \ -u "$FINVIA_API_KEY:" ``` O campo `status` da resposta mostra a situação atual. Quando a subconta é aprovada, `approvedAt` passa a ter a data da aprovação. Use o aviso de mudança de status como gatilho principal e a consulta para confirmar ou para casos sem aviso (como `pending` e `inactive`). Para acompanhar várias subcontas, `GET /v1/submerchants` aceita o filtro `status` com os sete valores. Para mais de um status, repita o parâmetro: `?status=pending&status=correcting`. Veja os demais filtros em [Listar subcontas](/referencia/fast-connect/listar-subcontas). ### 4. Obtenha as chaves da subconta ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/api-keys" \ -u "$FINVIA_API_KEY:" ``` ```json 200 theme={null} { "publicKey": "pk_2vorkDcXyvzifL63YX09S9VqcnI", "secretKey": "sk_2vorkDcXyvzifL63YX09S9VqcnI" } ``` Se a subconta não tiver chaves, a resposta é: ```json 404 theme={null} { "statusCode": 404, "message": "API keys not found for this submerchant." } ``` Em modo de teste, as chaves vêm com prefixo `sk_test_` e `pk_test_`. > [!WARNING] > > A `secretKey` é a chave secreta da subconta: com ela, a sua plataforma cria cobranças em nome da subconta. Guarde em cofre de segredos, no servidor, associada ao `id` da subconta. Nunca envie a chave secreta para o vendedor por e-mail ou mensagem, nem para o navegador. ### 5. Corrija um cadastro em `correcting` Quando a Finvia pede correções, o aviso chega com `status` `correcting` e o motivo em `rejectionReason`. A correção dos dados é feita pelo painel da Finvia, na gestão de subcontas (a API não oferece essa operação). Depois do reenvio, a subconta volta para a análise. O status `rejected` indica que o cadastro foi reprovado. > [!NOTE] > > **Para o negócio:** combine com o time de operação quem acompanha as correções pendentes no painel. Uma boa prática é mostrar o `rejectionReason` ao vendedor na sua plataforma, coletar o dado ou documento correto e só então fazer a correção no painel. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` na criação, com `message` em lista | Campo obrigatório ausente, enum inválido, país em alpha-2 (`BR`) ou documento com dígito verificador inválido | Confira os blocos obrigatórios desta página e os valores de `productType`, `gender`, `accountType` e `country` | | `400` `Email already registered` | Já existe usuário do painel com o e-mail de `user.email` | Use outro e-mail | | `409` com "Já existe um cadastro com este CNPJ" | CNPJ já cadastrado em outra subconta da mesma master ou igual ao da master | Procure a subconta existente com `companyTaxId` em [Listar subcontas](/referencia/fast-connect/listar-subcontas) | | Criação rejeitada com `canAccessDashboard: true` | Objeto `user` ausente ou telefone fora do E.164 | Envie `user` com `fullName`, `email` e `phone` no formato `+5511987654321` | | `400` no envio de documentos | Formato não aceito, arquivo acima de 50 MB, nenhum arquivo ou nome de campo inválido | Use JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF até 50 MB e os nomes de campo desta página | | `422` no envio de documentos | Subconta já aprovada | Depois da aprovação, novos envios são bloqueados | | `404` com "API keys not found for this submerchant." | A subconta não tem chaves | Confira o status da subconta e tente de novo depois da aprovação | | Nenhum aviso chega para `pending` ou `inactive` | Esses status não geram aviso | Consulte a subconta com `GET /v1/submerchants/{id}` | | `401` | Chave inválida ou mal formatada | Veja [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) | As mensagens de erro misturam português e inglês. Trate o erro pelo código HTTP, sem depender do texto da mensagem. ## Perguntas frequentes > [accordion] Posso enviar os documentos em várias chamadas? > > Sim. Cada chamada precisa ter pelo menos um arquivo. Você pode mandar os documentos da empresa em uma chamada e os do representante em outra. > [accordion] Consigo trocar um documento depois que a subconta foi aprovada? > > Não pela API. Depois da aprovação, novos envios são bloqueados e a rota responde `422`. > [accordion] O endereço do representante é obrigatório? > > Não. Se você não enviar `legalRepresentative.address`, o representante usa o endereço da empresa. > [accordion] Como sei por que a subconta foi recusada? > > O aviso de mudança de status traz o campo `rejectionReason` quando o status é `rejected` ou `correcting`. Para ver o status de cada documento de pessoa, use a listagem de representantes com `include=documents` ([Sócios e documentos](/guias/fast-connect/socios-e-documentos)). > [accordion] A subconta precisa de acesso ao painel? > > Não é obrigatório. Defina `canAccessDashboard` como `false` se a sua plataforma vai oferecer toda a experiência ao vendedor. Com `true`, informe o `user` que vai acessar o painel. > [accordion] Para que serve o softDescriptor? > > É o nome que aparece na fatura do cartão do cliente, com até 40 caracteres. > [accordion] Quanto tempo leva a análise? > > O tempo médio de credenciamento é de até 24 horas, e é mais rápido quando não há divergência nos documentos. Veja [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). ## Como testar Cenários do [roteiro de homologação](/homologacao/roteiro): | Código | O que comprovar | | - | - | | FC-01 | Criar a subconta com todos os campos obrigatórios e guardar o `id` | | FC-02 | Enviar um documento de cada tipo (contrato social, cartão CNPJ, documento frente e verso, selfie) | | FC-03 | Consultar a subconta até o status `active` | | FC-04 | Obter as chaves da subconta ativa | | FC-08 | Receber o aviso de mudança de status e responder com HTTP 2xx | ## Veja também > [card] [Sócios e documentos](/guias/fast-connect/socios-e-documentos) > > Sócios adicionais e envio de documentos com token. > [card] [Webhooks de conta](/guias/webhooks/conta) > > Formato completo do aviso de mudança de status. > [card] [Criar subconta](/referencia/fast-connect/criar-subconta) > > Referência completa da rota. > [card] [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento) > > Documentos exigidos, motivos de recusa e MCCs não aceitos. # Taxas da subconta Source: https://docs.fastpaybrasil.com/guias/fast-connect/taxas Consulte as taxas transacionais e de antecipação de uma subconta, junto com a razão social e o CNPJ, para mostrar ao lojista e para calcular o split. A rota `GET /v1/fast-connect/sub-accounts/{id}/fees-info` devolve as taxas de uma subconta (transacionais e de antecipação) e os dados cadastrais básicos dela: razão social e CNPJ. Com essas informações, a sua plataforma mostra ao lojista quanto ele paga em cada forma de pagamento e calcula o percentual de split correto para a sua comissão. ## Quando usar | Situação | Como a rota ajuda | | - | - | | Tela "minhas taxas" para o vendedor na sua plataforma | Lista as taxas por método, bandeira e parcela | | Simulador de recebimento ("quanto vou receber em 6x?") | Fornece os percentuais por parcela e a taxa fixa | | Comissão da plataforma sobre o valor bruto | Fornece `f` e `c` para o [Cálculo de split](/guias/fast-connect/calculo-split) | | Conferência cadastral | Traz razão social e CNPJ da subconta | > [!NOTE] > > **Para o negócio:** as taxas de cada subconta podem ser diferentes por método de pagamento, bandeira e número de parcelas. Consultar a rota evita que a sua plataforma mostre ao vendedor uma tabela desatualizada ou calcule comissões com taxas erradas. ## Como funciona **1. Autentique** Com a chave secreta (`sk_`, via Basic) da conta master ou da subconta. **2. Chame a rota** Como conta master, informe o `id` da subconta no caminho. Como subconta, a rota devolve sempre os dados da própria subconta. **3. Leia a resposta** O objeto `merchant` traz os dados cadastrais. A lista `fees` traz cada linha de taxa como está configurada. **4. Escolha a linha certa** Filtre por tipo, método, moeda e bandeira, e pegue o percentual da parcela desejada. A rota não faz esse trabalho por você. ## De onde vêm as taxas da subconta Na criação, a subconta recebe uma **cópia** das taxas vigentes da conta master. Depois disso, as taxas da subconta são independentes: * alterar as taxas da master **não muda** as das subcontas já criadas; * a Finvia pode replicar uma alteração para as subcontas por operação interna; peça ao suporte se precisar; * se a subconta chegar à pré-aprovação ainda sem nenhuma taxa (por exemplo, porque a master não tinha taxas quando ela foi criada), ela recebe uma cópia das taxas padrão da plataforma naquele momento. Na cobrança, a API usa só as taxas da própria conta que cobra, sem consultar a master nem as taxas padrão. Por isso, o que esta rota devolve já são as **taxas efetivas** da subconta. > [!WARNING] > > Se `fees` vier vazio, ou sem linha para o método e a moeda de uma cobrança, as cobranças dessa combinação são recusadas com `422` `Fees not configured`. Não use as taxas da master no lugar nem trate a lista vazia como taxa zero: acione o suporte da Finvia para configurar as taxas. > [!NOTE] > > `fees-info` não traz a reserva financeira nem a taxa de saque da subconta. O contrato público também não tem rota para a master ajustar as taxas de uma subconta. ## Comportamento por conta autenticada O resultado depende de **qual conta** está autenticada, além do `id` informado: | Conta autenticada | Comportamento | | - | - | | **Conta master** | Usa o `id` do caminho e devolve a subconta vinculada a ela. Um `id` de subconta de outra master, inexistente ou o próprio `id` da master responde `404`. Exige o Connect habilitado na master, senão `403` | | **Subconta** | Devolve **sempre os próprios dados**. O `id` do caminho é ignorado. Não depende do Connect estar habilitado | > [!TIP] > > **Para o desenvolvedor:** se a sua aplicação chama a rota com a chave da subconta, qualquer valor no `id` devolve os dados da própria subconta. Isso evita que uma subconta veja as taxas de outra. Com a chave da master, o `id` é obrigatório e precisa ser de uma subconta vinculada. ## Estrutura da resposta | Campo | Tipo | Descrição | | - | - | - | | `merchant.id` | string | Id da subconta (KSUID) | | `merchant.legalName` | string | Razão social | | `merchant.companyTaxId` | string | CNPJ, somente dígitos, 14 caracteres | | `fees` | array | Linhas de taxa da subconta, em lista plana, ordenada por tipo, método, moeda e bandeira. Vazia quando a subconta não tem taxas configuradas | | `fees[].feeType` | string | `tx_spread` (taxa transacional) ou `anticipation` (taxa de antecipação) | | `fees[].paymentMethod` | string ou `null` | Método de pagamento (ex.: `credit_card`, `pix`). `null` para taxas sem método associado | | `fees[].currencyCode` | string ou `null` | Moeda no padrão ISO 4217 (ex.: `BRL`). `null` quando não se aplica | | `fees[].brand` | string ou `null` | Bandeira do cartão (`visa`, `mastercard`, `elo`). `null` é a taxa padrão, que vale para qualquer bandeira sem taxa própria | | `fees[].definition.fixed` | number | Taxa fixa por transação, na moeda da linha | | `fees[].definition.percentages` | number\[] | Na taxa transacional, percentual por parcela: índice `0` = à vista (1x) até índice `11` = 12x. Na antecipação, só o índice `0` é usado | Os percentuais vêm em pontos percentuais: `2.99` significa 2,99%. ### Como ler `percentages` da taxa transacional | Índice | Parcelas | Exemplo (`[2.99, 3.49, 3.99, 4.49, 4.99, 5.49, ...]`) | | - | - | - | | `0` | 1x (à vista) | 2,99% | | `1` | 2x | 3,49% | | `2` | 3x | 3,99% | | `5` | 6x | 5,49% | | `11` | 12x | último valor da lista | Para uma venda em `n` parcelas, use o índice `n - 1`. ## Como chegar à taxa efetiva As taxas vêm **como estão configuradas**. A rota não escolhe a linha da bandeira nem a parcela. Para a **taxa transacional** (`tx_spread`): 1. Filtre as linhas com `feeType` `tx_spread`, `paymentMethod` e `currencyCode` iguais aos da venda. 2. No cartão, use a linha com `brand` igual à bandeira do cartão. Se ela não existir, use a linha `brand: null`. 3. O percentual é `definition.percentages[parcelas - 1]`. A taxa fixa é `definition.fixed`, cobrada por transação. Para a **taxa de antecipação** (`anticipation`): * só `definition.percentages[0]` é usado; * é uma taxa **mensal**, multiplicada pelo número de meses até o vencimento da parcela, com mínimo de 1 mês; * só incide quando o recebível é antecipado. Sem antecipação, ela não é cobrada. O desenho abaixo resume como escolher, na lista `fees`, a linha e o percentual que valem para uma venda. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Lista fees da subconta
GET .../fees-info"]):::finvia Q1{"Qual taxa
você procura?"}:::decisao TX["Filtre as linhas tx_spread
pelo método e pela moeda
da venda"]:::neutro Q2{"Encontrou
alguma linha?"}:::decisao ERR["Cobrança recusada
422 Fees not configured
acione o suporte"]:::erro Q3{"Há linha com a
bandeira do cartão?"}:::decisao BR["Use a linha
da bandeira"]:::neutro NUL["Use a linha
brand: null"]:::neutro RES(["Taxa da venda
percentages[parcelas − 1]
+ definition.fixed"]):::ok ANT["Linha anticipation
percentages[0] por mês"]:::neutro QA{"O recebível
foi antecipado?"}:::decisao ANTSIM(["Taxa mensal × meses
até o vencimento
mínimo de 1 mês"]):::alerta ANTNAO(["Não é cobrada"]):::neutro INI --> Q1 Q1 -->|"transacional"| TX Q1 -->|"antecipação"| ANT TX --> Q2 Q2 -->|"não"| ERR Q2 -->|"sim"| Q3 Q3 -->|"sim"| BR Q3 -->|"não, ou é Pix"| NUL BR --> RES NUL --> RES ANT --> QA QA -->|"sim"| ANTSIM QA -->|"não"| ANTNAO classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` O código abaixo, também usado em [Cálculo de split](/guias/fast-connect/calculo-split), faz a seleção da taxa transacional: ```ts TypeScript theme={null} interface FeeItem { feeType: "tx_spread" | "anticipation"; paymentMethod: string | null; currencyCode: string | null; brand: string | null; definition: { fixed: number; percentages: number[] }; } interface Filtro { paymentMethod: string; // ex.: "credit_card" currencyCode: string; // ex.: "BRL" brand: string | null; // ex.: "visa"; null no Pix parcelas: number; // ex.: 2; 1 no Pix } function obterTaxasFinvia(fees: FeeItem[], filtro: Filtro) { const candidatas = fees.filter( (i) => i.feeType === "tx_spread" && i.paymentMethod === filtro.paymentMethod && i.currencyCode === filtro.currencyCode, ); // a linha da bandeira tem prioridade; cai em brand: null quando não houver const linha = candidatas.find((i) => i.brand === filtro.brand) ?? candidatas.find((i) => i.brand === null); if (!linha) { // sem taxa para a combinação: a cobrança seria recusada com 422 Fees not configured throw new Error("Taxa não configurada para este método e moeda. Fale com o suporte da Finvia."); } const percentual = linha.definition.percentages[filtro.parcelas - 1]; if (percentual === undefined) { throw new Error(`Sem taxa para ${filtro.parcelas} parcelas.`); } return { taxaPercentualFinvia: percentual / 100, // f taxaFixaFinvia: linha.definition.fixed, // c }; } // Taxa de antecipação de uma parcela, em pontos percentuais (só quando antecipada) function taxaAntecipacao(fees: FeeItem[], paymentMethod: string, currencyCode: string, mesesAteVencimento: number) { const linha = fees.find( (i) => i.feeType === "anticipation" && i.paymentMethod === paymentMethod && i.currencyCode === currencyCode, ); if (!linha) return 0; return linha.definition.percentages[0] * Math.max(1, mesesAteVencimento); } ``` ### Exemplo de seleção Considere uma subconta com estas linhas (valores ilustrativos): ```json theme={null} { "merchant": { "id": "2v2TGGb4NHTQWCiMmnelz2WVOZP", "legalName": "LOJA EXEMPLO LTDA", "companyTaxId": "11222333000181" }, "fees": [ { "feeType": "anticipation", "paymentMethod": "credit_card", "currencyCode": "BRL", "brand": null, "definition": { "fixed": 0, "percentages": [1.99] } }, { "feeType": "tx_spread", "paymentMethod": "credit_card", "currencyCode": "BRL", "brand": null, "definition": { "fixed": 0.5, "percentages": [3.19, 3.69, 4.19, 4.69, 5.19, 5.69, 6.19, 6.69, 7.19, 7.69, 8.19, 8.69] } }, { "feeType": "tx_spread", "paymentMethod": "credit_card", "currencyCode": "BRL", "brand": "visa", "definition": { "fixed": 0.5, "percentages": [2.99, 3.49, 3.99, 4.49, 4.99, 5.49, 5.99, 6.49, 6.99, 7.49, 7.99, 8.49] } }, { "feeType": "tx_spread", "paymentMethod": "pix", "currencyCode": "BRL", "brand": null, "definition": { "fixed": 0, "percentages": [1.5] } } ] } ``` | Venda | Linha `tx_spread` usada | Taxa transacional | Taxa fixa | | - | - | - | - | | Visa em 6x | `brand: "visa"`, índice 5 | 5,49% | R\$ 0,50 | | Mastercard em 6x | `brand: null` (não há linha Mastercard), índice 5 | 5,69% | R\$ 0,50 | | Visa à vista | `brand: "visa"`, índice 0 | 2,99% | R\$ 0,50 | | Pix | `pix`, valor único | 1,5% | R\$ 0,00 | Em uma venda Visa de R\$ 600,00 em 6x, a taxa transacional soma `600 × 5,49% + 0,50 = R$ 33,44`, e o valor líquido é R\$ 566,56. Se o lojista antecipar, cada parcela paga ainda a antecipação: com a taxa mensal de 1,99% do exemplo, uma parcela que vence em 3 meses paga 1,99% × 3 = 5,97% sobre o valor dela. ## Passo a passo ```bash cURL (conta master) theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info" \ -u "$FINVIA_API_KEY:" ``` ```bash cURL (subconta) theme={null} # Com a chave da subconta, o id do caminho é ignorado curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info" \ -u "$SUBCONTA_SECRET_KEY:" ``` ```javascript Node.js theme={null} async function consultarFeesInfo(subcontaId) { const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( `https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/${subcontaId}/fees-info`, { headers: { Authorization: `Basic ${credentials}` } }, ); if (!response.ok) { const erro = await response.json(); throw new Error(`${erro.statusCode}: ${erro.message}`); } return response.json(); // { merchant, fees } } ``` ### Mostrar as taxas ao lojista Com a lista `fees`, a sua plataforma monta uma tabela por método e parcela. O exemplo abaixo continua o bloco da função `obterTaxasFinvia`, mais acima nesta página: ```javascript Node.js theme={null} function tabelaDeTaxasCartao(fees, bandeira) { const linhas = []; for (let parcelas = 1; parcelas <= 12; parcelas++) { const { taxaPercentualFinvia, taxaFixaFinvia } = obterTaxasFinvia(fees, { paymentMethod: 'credit_card', currencyCode: 'BRL', brand: bandeira, parcelas, }); linhas.push({ parcelas: `${parcelas}x`, percentual: `${(taxaPercentualFinvia * 100).toFixed(2)}%`, fixa: `R$ ${taxaFixaFinvia.toFixed(2)}`, }); } return linhas; } ``` ### Usar no cálculo do split A taxa transacional alimenta a fórmula do split quando a sua comissão é sobre o valor bruto. Veja o exemplo completo em [Cálculo de split](/guias/fast-connect/calculo-split). > [!NOTE] > > Por padrão, o split incide sobre o valor líquido da taxa transacional. A taxa de antecipação só reduz a base do split quando o originador antecipa o recebível. Veja [Split de pagamentos](/guias/fast-connect/split). ## Erros comuns | HTTP | Mensagem | Causa | Como resolver | | - | - | - | - | | `401` | `Não autorizado` | Credencial inválida ou ausente | Confira a chave e o formato do Basic ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)) | | `403` | `Fast Connect não habilitado para esta conta` | Conta não é merchant ou a master não tem o Connect habilitado | Peça à Finvia a liberação do módulo | | `404` | `Subconta não encontrada` | Com a chave da master: `id` de subconta não vinculada, inexistente ou o `id` da própria master | Use o `id` de uma subconta sua. Para ver as taxas da master, esta rota não serve | | `fees` vazio | | A subconta não tem taxas configuradas; as cobranças dela são recusadas com `422` `Fees not configured` | Acione o suporte da Finvia para configurar | | Taxas da subconta diferentes das da master | | As taxas são copiadas só na criação; depois, são independentes | Peça à Finvia a replicação, se for o caso | | Taxa errada em uma bandeira | | Linha `brand: null` usada quando havia linha da bandeira | Priorize a linha da bandeira | ## Perguntas frequentes > [accordion] A subconta recebe as taxas da master? > > Ela recebe uma cópia das taxas da master no momento da criação. Depois disso, as taxas são independentes: mudar as taxas da master não altera as das subcontas já criadas. > [accordion] Por que fees veio vazio? > > A subconta não tem taxas configuradas. Nesse caso, as cobranças dela são recusadas com `422` `Fees not configured`. Acione o suporte da Finvia; não use as taxas da master no lugar. > [accordion] Consigo consultar as taxas da própria conta master por esta rota? > > Não. Com a chave da master, informar o `id` da própria master responde `404`. A rota é para subcontas. > [accordion] A subconta precisa do Connect habilitado para consultar? > > Não. Autenticada como subconta, a rota devolve os próprios dados mesmo sem essa configuração. A exigência vale para a conta master. > [accordion] Os percentuais vêm em fração ou em pontos percentuais? > > Em pontos percentuais: `2.99` é 2,99%. Para usar na fórmula do split, divida por 100. > [accordion] A rota mostra a taxa de saque ou a reserva financeira? > > Não. `fees-info` traz só as taxas transacionais e de antecipação. ## Como testar O roteiro de homologação não tem cenário próprio para esta rota. Se a sua integração usa as taxas para calcular o split, os cenários **SPL-05** (conferência do percentual e da base de cada recebedor) e **SPL-06** (Pix e cartão parcelado) do [roteiro de homologação](/homologacao/roteiro) comprovam que a leitura das taxas está correta. ## Veja também > [card] [Cálculo de split](/guias/fast-connect/calculo-split) > > Use as taxas para calcular a comissão sobre o bruto. > [card] [Taxas e dados (referência)](/referencia/fast-connect/taxas-e-dados) > > Referência completa da rota. > [card] [Split de pagamentos](/guias/fast-connect/split) > > Regras e exemplos de divisão de vendas. > [card] [Connect: visão geral](/guias/fast-connect/visao-geral) > > Conta master, subcontas e mapa das rotas. # Connect: visão geral Source: https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral Crie e gerencie subcontas vinculadas à sua conta, divida o valor das vendas entre elas e permita que cada uma saque o próprio saldo. O Connect é o módulo da Finvia para quem precisa operar várias contas de recebimento debaixo de uma conta master: marketplaces, plataformas de venda e PSPs (provedores de serviços de pagamento) parceiros que cadastram seus lojistas como subcontas. Com ele, a sua empresa cria **subcontas** para os vendedores ou clientes dela, controla taxas, permissões e acessos de cada uma, divide o valor das vendas entre as contas (split) e acompanha tudo com rastreabilidade por transação. > [!NOTE] > > As rotas e algumas mensagens da API ainda usam o nome anterior do módulo, como `/v1/fast-connect/...` e `Fast Connect not enabled.`. Eles aparecem nesta documentação exatamente como a API devolve. ## Quando usar | Situação | O Connect resolve? | | - | - | | Marketplace com vários vendedores, em que cada venda precisa ficar registrada no vendedor certo | Sim. Cada vendedor vira uma subconta e cobra com as próprias chaves | | Plataforma (SaaS, loja virtual, infoprodutos) que cobra comissão sobre as vendas dos clientes | Sim. A comissão é separada automaticamente por split em cada venda | | PSP parceiro que cadastra seus lojistas como subcontas e precisa de cadastro, análise documental (KYC) e saque por lojista | Sim. Cadastro, documentos, status de aprovação e saque ficam na API | | Empresa com um único CNPJ que só vende os próprios produtos | Não precisa. Use a conta normal e a [cobrança](/referencia/cobrancas/criar) sem split | | Dividir uma venda com empresas que não estão no seu [grupo Connect](/glossario) (a conta master e as subcontas dela) | Não. Todas as contas do split precisam pertencer ao mesmo grupo | > [!NOTE] > > **Para o negócio:** o Connect não é liberado automaticamente. O módulo precisa ser habilitado pela Finvia na sua conta. Fale com o time comercial ou de suporte para pedir a liberação antes de começar a integração. PSPs e plataformas que usam o Connect seguem as [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento): split obrigatório em toda transação de PSP, pré-validação do lojista, documentos exigidos e ramos não aceitos. ## Conta master e subconta O Connect trabalha com dois papéis: | Papel | Quem é | O que pode fazer | | - | - | - | | **Conta master** (MerchantMaster) | A sua empresa, liberada pela Finvia para usar o módulo | Criar subcontas, enviar e consultar documentos, listar subcontas e sócios, obter as chaves de cada subconta, consultar as taxas de cada subconta, receber parte das vendas por split e originar vendas com split para subcontas | | **Subconta** (SubMerchant) | Cada vendedor, lojista ou cliente que você cadastra | Depois de aprovada, criar cobranças com as próprias chaves, dividir vendas com a master ou com outras subcontas do grupo, consultar as próprias taxas e solicitar saque do próprio saldo | Na criação, a subconta recebe uma **cópia das taxas, permissões e configurações vigentes da conta master**. Ela nasce com as condições comerciais que a Finvia definiu para a sua conta, e você não precisa configurar taxa por taxa a cada cadastro. Depois disso, as taxas da subconta são independentes: mudar as taxas da master não altera as das subcontas já criadas. O desenho abaixo mostra a estrutura de um grupo Connect: a master, as subcontas que ela cria e o que cada subconta recebe. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB FIN["Finvia
habilita o Connect"]:::finvia M["Conta master
sua empresa, PSP
ou plataforma"]:::lojista S1["Subconta 1
vendedor ou lojista"]:::lojista S2["Subconta 2
vendedor ou lojista"]:::lojista S3["Subconta N
vendedor ou lojista"]:::lojista OWN["Com status active:
chaves de API próprias,
vendas, saldo e saque"]:::ok FIN ==>|"1. libera o módulo"| M M -->|"2. cria com cópia das taxas,
permissões e configurações"| S2 M --> S1 M --> S3 S1 -.-> OWN S2 -.-> OWN S3 -.-> OWN classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` O split pode ir da master para uma subconta, de uma subconta para a master ou entre duas subcontas do mesmo grupo (veja [Relações de split permitidas](#relações-de-split-permitidas)). A subconta só usa as chaves, vende e saca depois de aprovada (`active`). > [!NOTE] > > A rota [`GET /v1/fast-connect/sub-accounts/{id}/fees-info`](/referencia/fast-connect/taxas-e-dados) devolve as taxas efetivas da subconta. Se `fees` vier vazio, as cobranças dela são recusadas até a Finvia configurar as taxas. Veja [Taxas da subconta](/guias/fast-connect/taxas). ## Como funciona **1. Liberação do módulo** A Finvia habilita o Connect na sua conta, que passa a ser uma conta master. **2. Cadastro da subconta** Você cria a subconta com `POST /v1/submerchants`, enviando dados da empresa, do representante legal, dos sócios (se houver) e da conta bancária. A subconta nasce com status `pending`. **3. Documentos e análise (KYC)** Você envia os documentos da empresa e das pessoas. A Finvia analisa o cadastro (KYC, a verificação de identidade e de dados da empresa) e o status muda para `pre_approved`, `correcting`, `active` ou `rejected`. Detalhes em [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) e [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). **4. Chaves da subconta** Com a subconta `active`, você obtém as chaves de API dela em `GET /v1/submerchants/{id}/api-keys`. **5. Vendas com split** A subconta cria cobranças com a chave dela, e o valor pode ser dividido com a master ou com outras subcontas. Veja [Split de pagamentos](/guias/fast-connect/split). **6. Liquidação e saque** Cada parte do split é repassada parcela a parcela, quando o recebível do originador é [liquidado](/glossario): no cartão, a cada 30 dias por parcela (D+30, D+60...); no Pix, logo após a confirmação do pagamento. O valor entra no saldo disponível de quem recebe. O saque da subconta vai por Pix para a chave CNPJ dela. Veja [Split de pagamentos](/guias/fast-connect/split) e [Saques da subconta](/guias/fast-connect/saques). O desenho abaixo mostra o caminho do dinheiro em uma venda com split, do pagamento ao saque da subconta. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB C(["Comprador"]):::comprador COB["Cobrança com a chave
da subconta originadora
POST /v1/charges com split"]:::lojista API["Finvia API
desconta as taxas"]:::finvia LIQ["Liquidação por parcela
cartão: D+30, D+60...
Pix: após a confirmação"]:::alerta REC["Saldo de quem recebe
o split: master ou
outra subconta do grupo"]:::ok ORI["Saldo da subconta
originadora: o que
não foi dividido"]:::ok SAQ["Saque da subconta
POST .../payout-requests
com a chave da master"]:::lojista BAN["Pix em BRL para a
chave CNPJ da subconta"]:::externo C -->|"1. paga"| COB COB -->|"2. envia"| API API -->|"3. valor líquido"| LIQ LIQ -->|"4. % do split"| REC LIQ -->|"4. restante"| ORI ORI -->|"5. pede o saque"| SAQ SAQ -->|"6. aprovação manual
da operação Finvia"| BAN classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 ``` Quem recebe o split também tem a parte dele liberada parcela a parcela, no mesmo ritmo da liquidação do originador. As regras de cada etapa estão em [Split de pagamentos](/guias/fast-connect/split) e [Saques da subconta](/guias/fast-connect/saques). ## Regras de negócio | Regra | Detalhe | | - | - | | Liberação | O módulo é habilitado pela Finvia. Sem a liberação, rotas como a de taxas (`fees-info`) e a de saque respondem `403` | | Cópia de taxas | Na criação, a subconta recebe uma cópia das taxas, permissões e configurações da master. Depois, as taxas são independentes | | Aprovação | A subconta só pode transacionar depois de aprovada (status `active`) | | Chaves | As chaves de cada subconta são obtidas pela master em `GET /v1/submerchants/{id}/api-keys` | | Split | A soma dos percentuais não pode passar de 100%. O que não for dividido fica com o [originador](/glossario), a conta que criou a cobrança | | Split em PSP | Toda transação de PSP precisa ter split entre a conta master (PSP) e a subconta (lojista). Split de 100% para o PSP não é permitido | | Grupo | Todas as contas de um split precisam pertencer ao mesmo grupo Connect | | Base do split | O percentual é aplicado sobre o [valor líquido](/glossario), depois das taxas da Finvia | | Saque da subconta | Sempre em BRL, via Pix, para a chave Pix CNPJ da subconta, com aprovação manual da operação Finvia | ### Relações de split permitidas | Quem origina a venda | Quem pode receber parte dela | | - | - | | Conta master | Subconta | | Subconta | Conta master | | Subconta | Outra subconta do mesmo grupo | > [!WARNING] > > Para que a venda fique vinculada à subconta que vendeu, a cobrança precisa ser criada com a **chave secreta da subconta originadora**, obtida em `GET /v1/submerchants/{id}/api-keys`. É a chave usada na chamada que define quem originou a venda. ## Qual chave usar em cada chamada | Operação | Rota | Autenticação | | - | - | - | | Criar subconta | `POST /v1/submerchants` | Basic, chave secreta da master | | Listar subcontas | `GET /v1/submerchants` | Basic, chave secreta da master | | Consultar subconta | `GET /v1/submerchants/{id}` | Basic, chave secreta da master | | Enviar documentos (direto) | `POST /v1/submerchants/{id}/document` | Basic, chave secreta da master | | Emitir token de upload | `POST /v1/submerchants/{merchantId}/document/upload-token` | Basic, chave secreta da master | | Enviar documentos com token | `POST /v1/document-uploads` | Bearer, com o **token de upload** (não é a chave de API) | | Listar sócios e documentos | `GET /v1/submerchants/{merchantId}/legal-representatives` | Basic, chave secreta da master | | Obter as chaves da subconta | `GET /v1/submerchants/{id}/api-keys` | Basic, chave secreta da master | | Consultar taxas e dados cadastrais | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | Basic, chave secreta da master ou da subconta | | Criar cobrança com split | `POST /v1/charges` | Basic, chave secreta de quem **origina** a venda (normalmente a subconta) | | Solicitar saque da subconta | `POST /v1/submerchants/{merchantId}/payout-requests` | Basic, chave secreta da master | | Listar saques | `GET /v1/payout-requests` | Basic, chave secreta da master | > [!NOTE] > > Nas rotas de saque e de saldo, a chave age com as permissões do usuário que a gerou: uma chave de usuário com perfil **Desenvolvedor** recebe `403` `Acesso negado`. Com a chave de teste, a criação de saque responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`, porque não existe saque no Modo Teste. > [!TIP] > > **Para o desenvolvedor:** guarde as chaves de cada subconta no seu cofre de segredos, associadas ao `id` da subconta. Na hora de criar a cobrança, a sua aplicação escolhe a chave pela subconta que está vendendo. A chave secreta da subconta segue as mesmas regras da sua: nunca vai para o navegador nem para o aplicativo. ## Mapa das rotas | Grupo | Rota | Página | | - | - | - | | Subcontas | `POST /v1/submerchants` | [Criar subconta](/referencia/fast-connect/criar-subconta) | | Subcontas | `GET /v1/submerchants` | [Listar subcontas](/referencia/fast-connect/listar-subcontas) | | Subcontas | `GET /v1/submerchants/{id}` | [Consultar subconta](/referencia/fast-connect/consultar-subconta) | | Documentos | `POST /v1/submerchants/{id}/document` | [Enviar documentos](/referencia/fast-connect/enviar-documentos) | | Documentos | `POST /v1/submerchants/{merchantId}/document/upload-token` | [Criar token de upload](/referencia/fast-connect/criar-token-upload) | | Documentos | `POST /v1/document-uploads` | [Enviar documentos com token](/referencia/fast-connect/enviar-documentos-com-token) | | Sócios | `GET /v1/submerchants/{merchantId}/legal-representatives` | [Listar representantes](/referencia/fast-connect/listar-representantes) | | Chaves | `GET /v1/submerchants/{id}/api-keys` | [Chaves de API](/referencia/fast-connect/chaves-de-api) | | Taxas | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | [Taxas e dados](/referencia/fast-connect/taxas-e-dados) | | Saques | `POST /v1/submerchants/{merchantId}/payout-requests` | [Criar saque da subconta](/referencia/fast-connect/criar-saque) | | Saques | `GET /v1/payout-requests` | [Listar saques](/referencia/saques/listar) | | Cobranças | `POST /v1/charges` (campo `split`) | [Criar cobrança](/referencia/cobrancas/criar) | ## Passo a passo resumido Um primeiro contato com o módulo, depois da liberação. Os detalhes de cada etapa estão nas páginas seguintes. ```bash 1. Criar a subconta (chave da master) theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d @subconta.json ``` ```bash 2. Consultar o status (chave da master) theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI" \ -u "$FINVIA_API_KEY:" ``` ```bash 3. Obter as chaves (subconta active) theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/api-keys" \ -u "$FINVIA_API_KEY:" ``` ```bash 4. Vender com split (chave da subconta) theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$SUBCONTA_SECRET_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "BRL", "customer": { "name": "Ana Lima", "email": "ana@email.com" }, "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, "items": [ { "title": "Aula de cerâmica online", "type": "digital", "description": "Turma de sábado", "unit_price": 100, "quantity": 1 } ], "split": [ { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 10 } ] }' ``` No passo 4, `36OO3bcGjhPjjF3tzrqOGcmQuKo` representa o `id` da conta que recebe a comissão (por exemplo, a master). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` com "Connect não habilitado para esta conta" ou "Connect not enabled." | Módulo não habilitado na sua conta | Peça à Finvia a liberação do Connect | | `404` ao buscar as chaves da subconta | A subconta não tem chaves ou não pertence à master | Confira o `id` e o status da subconta | | Cadastro de lojista recusado | Documento inválido, ramo não aceito, empresa inapta, entre outros | Veja os motivos em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento) | | Venda não aparece vinculada à subconta | Cobrança criada com a chave da master | Crie a cobrança com a chave secreta da subconta originadora | | Comissão recebida menor que a esperada | O percentual do split incide sobre o líquido, depois das taxas | Ajuste o percentual com a fórmula de [Cálculo de split](/guias/fast-connect/calculo-split) | | `404` em rotas de subconta | A subconta não pertence à master autenticada | Confira o `id` e a chave usada | ## Perguntas frequentes > [accordion] Como peço a liberação do Connect? > > Pelo seu contato comercial ou pelo suporte da Finvia. O módulo é instalado e habilitado pela Finvia na sua conta, que passa a funcionar como conta master. > [accordion] Preciso configurar as taxas de cada subconta? > > Não na criação. A subconta recebe uma cópia das taxas, permissões e configurações da master no momento em que é criada. Depois disso, as taxas dela são independentes. Para conferir as taxas de uma subconta, use a rota de [taxas e dados](/referencia/fast-connect/taxas-e-dados). Se `fees` vier vazio, fale com o suporte: as cobranças dessa subconta são recusadas até a configuração. > [accordion] A subconta pode vender antes de ser aprovada? > > Não. A subconta só fica apta a transacionar com status `active`. > [accordion] A subconta pode acessar o painel da Finvia? > > Pode, se você quiser. Na criação, o campo `canAccessDashboard` define o acesso. Quando ele é `true`, você informa também o objeto `user` com nome, e-mail e telefone do usuário que vai entrar no painel. > [accordion] Posso dividir uma venda entre duas subcontas sem passar pela master? > > Sim. A relação subconta para subconta é permitida, desde que as duas pertençam ao mesmo grupo Connect. ## Como testar A homologação do Connect está no [roteiro de homologação](/homologacao/roteiro): * **FC-01 a FC-08**: criação da subconta, envio de documentos, consulta até `active`, obtenção das chaves, cobrança com a chave da subconta, cobrança com split, saque da subconta e recebimento do aviso de mudança de status. * **SPL-01 a SPL-06**: cobranças com split, validações e conferência dos valores. Use as chaves de teste (`sk_test_`) da master. As chaves de subconta em modo de teste também vêm com prefixo `sk_test_` e `pk_test_`. O saque (FC-07) não existe no Modo Teste: com chave de teste, a resposta é `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. Veja no roteiro como esse cenário é conferido. ## Veja também > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Cadastro, documentos e status de aprovação. > [card] [Split de pagamentos](/guias/fast-connect/split) > > Regras e exemplos de divisão de vendas. > [card] [Saques da subconta](/guias/fast-connect/saques) > > Como a subconta retira o saldo via Pix. > [card] [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento) > > Regras para PSPs e plataformas, documentos e MCCs não aceitos. > [card] [Marketplace e PSP](/casos-de-uso/marketplace-psp) > > Caso de uso completo com subcontas e split. # Saldos e meios de pagamento Source: https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento Consulte o saldo da sua conta por moeda, saque o saldo disponível por Pix e descubra quais formas de pagamento estão habilitadas para o checkout. Três tarefas do dia a dia financeiro ficam nesta página. `GET /v1/wallets` mostra o saldo da conta por moeda: quanto está disponível, quanto ainda vai ser liberado e quanto está reservado. `POST /v1/payout-requests` saca o saldo disponível por Pix para a chave CNPJ da empresa. `GET /v1/payment-methods` lista as formas de pagamento habilitadas para a conta, para montar o checkout com o que está de fato disponível. > [!NOTE] > > **Para o negócio:** com o saldo e o saque pela API, o financeiro acompanha o caixa e pede saques do próprio sistema de gestão, sem entrar no painel. A Finvia oferece cartão de crédito (inclusive cartão salvo e Apple Pay) e Pix; a lista de meios de pagamento mostra o que está habilitado na sua conta. ## Quando usar | Situação | Rota | | - | - | | Mostrar o saldo num dashboard financeiro ou ERP | `GET /v1/wallets` | | Verificar se há saldo e se o saque está habilitado antes de pedir um saque | `GET /v1/wallets` | | Sacar o saldo disponível da sua conta | `POST /v1/payout-requests` | | Acompanhar um saque pedido | `GET /v1/payout-requests` | | Montar o checkout com as formas de pagamento da conta | `GET /v1/payment-methods` | | Testar se a chave de API está funcionando | `GET /v1/payment-methods` (resposta `200` confirma a autenticação) | O saque do saldo de uma **subconta** do Connect é outro fluxo: veja [Saques da subconta](/guias/fast-connect/saques). ## Como funciona **1. Consulte o saldo** `GET /v1/wallets?merchantId=...` devolve uma lista com uma carteira por moeda, com `available` (disponível), `pending` (a liberar) e `reserved` (reservado), e `isWithdrawalEnabled`. **2. Peça o saque** `POST /v1/payout-requests` com o valor em reais e `externalAccountDetails` `{ "type": "pix" }`. A resposta `201` não tem corpo. **3. Acompanhe pela listagem** `GET /v1/payout-requests` com o `merchantId` da sua conta traz o saque mais recente primeiro, com `status` `pending`, `approved` ou `rejected`. O saque da conta master ou de conta sem Connect não gera webhook (só os saques de subconta geram, qualquer que seja a rota usada para criar). **4. Consulte os meios de pagamento** `GET /v1/payment-methods` devolve as formas de pagamento habilitadas, com países e moedas aceitos. ## Regras de negócio | Regra | Detalhe | | - | - | | Autenticação | As três rotas usam Basic com a chave secreta (`sk_`), como o resto da API | | Permissão da chave | A chave age com as permissões do usuário que a gerou. Uma chave de usuário com perfil **Desenvolvedor** recebe `403` `Acesso negado` em saldo (`/v1/wallets`) e em saques (`/v1/payout-requests`). A chave padrão da conta pertence ao proprietário e funciona em todas | | Saldo por moeda | `GET /v1/wallets` devolve uma carteira por moeda, em array e sem paginação. Exige `merchantId`; `currency` é opcional | | Valores do saldo | Na unidade da moeda: `1000.5` em BRL é R\$ 1.000,50 | | Saque | Só por Pix, em BRL, para a chave Pix CNPJ da própria conta | | Modo Teste | Não existe saque com a chave de teste: `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | | Meios de pagamento | `GET /v1/payment-methods` aceita os filtros opcionais `merchantId` e `currency` e devolve um array sem paginação | ## Saldo: GET /v1/wallets ### Campos da resposta | Campo | Tipo | Descrição | | - | - | - | | `currency` | string | Código da moeda da carteira | | `isWithdrawalEnabled` | boolean | Se o saque está habilitado nessa moeda | | `balance.available` | number | Saldo disponível | | `balance.pending` | number | Saldo pendente (ainda não liberado) | | `balance.reserved` | number | Saldo reservado | | `usdBalance.available` | number | Saldo disponível convertido para USD | | `usdBalance.pending` | number | Saldo pendente convertido para USD | | `usdBalance.reserved` | number | Saldo reservado convertido para USD | > [!NOTE] > > Use `available` como o valor que pode ser sacado. Um saque pedido sai do saldo disponível já na criação, mesmo antes da aprovação; se for recusado, o valor volta. ### Exemplo ```http REST (JSON) theme={null} GET /v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q¤cy=BRL HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q¤cy=BRL" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} // saldo.mjs (Node.js 18+, ESM) const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q¤cy=BRL', { headers: { Authorization: `Basic ${auth}` } }, ); const wallets = await response.json(); console.log(wallets); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q¤cy=BRL", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q¤cy=BRL")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q¤cy=BRL"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q¤cy=BRL", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q¤cy=BRL") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `200`: ```json theme={null} [ { "currency": "BRL", "isWithdrawalEnabled": true, "balance": { "available": 1000.5, "pending": 250, "reserved": 100 }, "usdBalance": { "available": 200.1, "pending": 50, "reserved": 20 } } ] ``` ### Caso de uso: saldo num dashboard Um ERP quer mostrar ao financeiro um cartão com o saldo do dia: ```javascript Node.js theme={null} // painel-saldo.mjs (Node.js 18+, ESM) const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const formatBRL = (v) => v.toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' }); async function getBalanceCard(merchantId) { const res = await fetch( `https://api-global.fastpaybrasil.com/v1/wallets?merchantId=${merchantId}¤cy=BRL`, { headers: { Authorization: `Basic ${auth}` } }, ); const [brl] = await res.json(); if (!brl) return null; return { disponivel: formatBRL(brl.balance.available), // "R$ 1.000,50" aLiberar: formatBRL(brl.balance.pending), // "R$ 250,00" reservado: formatBRL(brl.balance.reserved), // "R$ 100,00" podeSacar: brl.isWithdrawalEnabled && brl.balance.available > 0, }; } console.log(await getBalanceCard('2RhQg9M7ZCg3X3nMb9W1kX8Q')); ``` > [!TIP] > > **Para o desenvolvedor:** a resposta é um array. Se a conta não tem carteira na moeda filtrada, o array pode vir vazio. Trate esse caso antes de ler `balance`. ## Saque da própria conta: POST /v1/payout-requests O saque transfere o saldo disponível da sua conta para a conta bancária da empresa, por **Pix**, na **chave Pix CNPJ** igual ao CNPJ do cadastro. Vale para qualquer conta, com ou sem Connect. > [!WARNING] > > O saque é enviado por Pix para a chave CNPJ da sua conta (o mesmo CNPJ do cadastro). Antes de solicitar saques, cadastre esse CNPJ como chave Pix em uma conta bancária da empresa. Não é possível escolher outra chave. Se a chave não existir, o Pix não é concluído; nesse caso, fale com o suporte. O desenho abaixo mostra o caminho de um saque da própria conta, do saldo consultado ao Pix na chave CNPJ. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB GW(["GET /v1/wallets
saldo por moeda"]):::lojista AV["available
saldo disponível,
é o que pode ser sacado"]:::ok PR["pending e reserved
a liberar e reservado,
não podem ser sacados"]:::neutro POST["POST /v1/payout-requests
amount em reais, BRL,
externalAccountDetails pix"]:::lojista R{"Resposta
da criação"}:::decisao E403["403 · não existe
saque no Modo Teste"]:::erro E422["422: saldo insuficiente,
acima do limite ou já
há saque pending"]:::erro PEN["201 sem corpo · pending
o valor bruto já saiu
do disponível"]:::alerta LST["GET /v1/payout-requests
traz o id e o status
webhook só em subconta"]:::lojista OP["Operação Finvia decide
ou aprovação automática
do Pix"]:::finvia APR["approved
Pix do valor líquido:
amount menos a taxa"]:::ok CNPJ[("Chave Pix CNPJ
da própria conta")]:::externo REJ["rejected
o valor volta ao
saldo disponível"]:::erro GW --> AV GW --> PR AV -->|"valor a sacar"| POST --> R R -->|"chave de teste"| E403 R -->|"regra violada"| E422 R -->|"201"| PEN PEN -.-> LST PEN --> OP OP -->|"aprova"| APR --> CNPJ OP -->|"recusa"| REJ classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ### Regras | Regra | Detalhe | | - | - | | Corpo | `merchantId` (a sua própria conta), `amount` em reais, `currency` `BRL` e `externalAccountDetails` `{ "type": "pix" }` | | Valor | Em **reais**, maior que zero: `100.50` é R\$ 100,50 | | Saldo | O saldo disponível precisa ser maior ou igual a `amount`. O valor bruto sai do saldo disponível já na criação | | Limite | Há um limite máximo por saque configurado para a sua conta (`422` `Maximum withdrawal amount is X`) | | Pendentes | Por padrão, só um saque `pending` por moeda. A operação Finvia pode liberar mais de um para a conta | | Taxa | A taxa de saque da conta (fixa + percentual) é descontada: o valor transferido é `amount` menos a taxa | | Aprovação | O saque nasce `pending` e é aprovado ou recusado pela operação. A conta pode ter aprovação automática do Pix configurada | | Resposta | `201` **sem corpo**. Para obter o `id`, use a listagem | | Aviso | Só os saques de subconta geram webhook, qualquer que seja a rota usada para criar. O saque da conta master ou de conta sem Connect não gera webhook: acompanhe pela listagem | ### Exemplo ```http REST (JSON) theme={null} POST /v1/payout-requests HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 500, "currency": "BRL", "externalAccountDetails": { "type": "pix" } } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/payout-requests" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 500, "currency": "BRL", "externalAccountDetails": { "type": "pix" } }' ``` ```javascript Node.js theme={null} // saque.mjs (Node.js 18+, ESM) const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const base = 'https://api-global.fastpaybrasil.com'; const merchantId = '2RhQg9M7ZCg3X3nMb9W1kX8Q'; const response = await fetch(`${base}/v1/payout-requests`, { method: 'POST', headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ merchantId, amount: 500, // R$ 500,00 currency: 'BRL', externalAccountDetails: { type: 'pix' }, }), }); if (response.status !== 201) { const erro = await response.json(); throw new Error(`${response.status}: ${erro.message}`); } // 201 sem corpo: o saque mais recente da conta é o que acabou de ser criado const lista = await fetch(`${base}/v1/payout-requests?merchantId=${merchantId}&page=1&size=1`, { headers: { Authorization: `Basic ${auth}` }, }).then((r) => r.json()); const saque = lista.data[0]; console.log(saque.id, saque.status, Number(saque.amount) - Number(saque.payoutFee)); // valores chegam como texto ``` ```python Python theme={null} import os import requests payload = { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 500, "currency": "BRL", "externalAccountDetails": { "type": "pix", }, } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/payout-requests", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2RhQg9M7ZCg3X3nMb9W1kX8Q', 'amount' => 500, 'currency' => 'BRL', 'externalAccountDetails' => [ 'type' => 'pix', ], ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/payout-requests'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 500, "currency": "BRL", "externalAccountDetails": { "type": "pix" } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payout-requests")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 500, "currency": "BRL", "externalAccountDetails": { "type": "pix" } } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/payout-requests"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 500, "currency": "BRL", "externalAccountDetails": { "type": "pix" } }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/payout-requests", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/payout-requests") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "merchantId" => "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount" => 500, "currency" => "BRL", "externalAccountDetails" => { "type" => "pix", }, }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ### Acompanhe o status `GET /v1/payout-requests` com o `merchantId` da sua conta mostra cada saque com `status`: | Status | O que significa | | - | - | | `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda decisão | | `approved` | Aprovado e enviado para pagamento. O Pix do valor líquido é enviado nesse momento | | `rejected` | Recusado. O valor volta ao saldo disponível | Na listagem, `amount` e `payoutFee` chegam como texto decimal com 8 casas (ex.: `"500.00000000"`). Converta antes de calcular. Veja todos os filtros em [Listar saques](/referencia/saques/listar). > [!WARNING] > > Se a criação responder `422` `Payout execution failed: ...` (acontece só com aprovação automática), não repita o pedido de imediato. A solicitação pode ter ficado criada como `pending`. Consulte a listagem antes de tentar de novo. **Em validação (V-49):** o suporte está definindo o procedimento quando o Pix do saque falha (prazo e como o saldo volta). A API não confere se o CNPJ está cadastrado como chave Pix, e o status do saque não mostra essa falha. Enquanto isso, se o valor de um saque não chegar, abra um chamado com o `id` do saque. ## Meios de pagamento: GET /v1/payment-methods ### Regras | Regra | Detalhe | | - | - | | Parâmetros | Ambos opcionais: `merchantId` e `currency` | | Formato da resposta | **Array**, sem paginação | | Autenticação | Basic, com a chave secreta (`sk_`) | ### Campos da resposta | Campo | Tipo | Descrição | | - | - | - | | `id` | string | Identificador do meio de pagamento | | `name` | string | Nome técnico | | `countries` | string\[] | Países em que o meio está disponível (ISO alpha-3, ex.: `BRA`) | | `currencies` | string\[] | Moedas aceitas | | `description` | string | Nome para exibir na interface | ### Exemplo ```http REST (JSON) theme={null} GET /v1/payment-methods?currency=BRL HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL', { headers: { Authorization: `Basic ${credentials}` }, }); const methods = await response.json(); console.log(methods); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `200` (exemplo ilustrativo; os valores dependem da sua conta): ```json theme={null} [ { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "name": "pix", "countries": ["BRA"], "currencies": ["BRL"], "description": "Pix" } ] ``` ### Caso de uso: checkout dinâmico Neste exemplo, o checkout consulta a lista na abertura da página e mostra só o que a conta aceita para a moeda e o país do pedido: ```javascript Node.js theme={null} // opcoes-checkout.mjs (Node.js 18+, ESM) const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); async function getCheckoutOptions({ currency, country }) { const res = await fetch( `https://api-global.fastpaybrasil.com/v1/payment-methods?currency=${currency}`, { headers: { Authorization: `Basic ${credentials}` } }, ); const methods = await res.json(); return methods .filter((m) => m.countries.includes(country)) .map((m) => ({ value: m.name, label: m.description })); } // Pedido em reais de um cliente no Brasil const options = await getCheckoutOptions({ currency: 'BRL', country: 'BRA' }); console.log(options); ``` > [!TIP] > > **Para o desenvolvedor:** você pode guardar a lista em cache por alguns minutos para não consultar a API a cada visita ao checkout. Defina o tempo de cache conforme a sua operação: a documentação não informa com que frequência a lista muda. > [!NOTE] > > A documentação não fixa o valor de `name` para Pix e cartão de crédito nessa lista. Ao mapear `name` para o `paymentMethod.type` de `POST /v1/charges`, confira os valores que a sua conta devolve. ## Erros comuns | Rota | Sintoma | Causa | Como resolver | | - | - | - | - | | Todas | `401` `Unauthorized` | Chave inválida ou Basic no formato errado | Confira o Basic com a chave secreta e os dois-pontos no fim | | `wallets`, `payout-requests` | `403` `Acesso negado` | Chave gerada por usuário com perfil Desenvolvedor | Use a chave padrão da conta ou gere uma com usuário Owner ou Manager | | `payout-requests` (criação) | `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chave de teste | Saques só existem em produção | | `payout-requests` (criação) | `422` `Insufficient balance. Required: X, Available: Y` | Saldo disponível menor que o valor | Consulte o saldo e peça um valor menor | | `payout-requests` (criação) | `422` `You already have a pending withdrawal request for this currency` | Saque anterior ainda pendente | Aguarde a decisão do saque anterior | | `payout-requests` (criação) | `422` `You can only create withdrawal requests for your own account` | `merchantId` de outra conta | Envie o `id` da sua conta | | `wallets` | `404` `Merchant not found` | `merchantId` inexistente ou fora do acesso da credencial | Confira o ID do merchant | | `wallets` | Resposta vazia | Sem carteira na moeda filtrada | Remova o filtro `currency` e confira as moedas disponíveis | Mais mensagens de erro do saque em [Solicitar saque](/referencia/saques/criar). ## Perguntas frequentes > [accordion] Qual saldo posso sacar? > > O valor de `balance.available`, desde que `isWithdrawalEnabled` seja `true` para a moeda e o valor respeite o limite por saque da conta. `pending` e `reserved` não estão disponíveis para saque. > [accordion] Posso sacar para outra chave Pix ou por transferência bancária? > > Não. O saque publicado nesta documentação é só por Pix, para a chave CNPJ da própria conta. > [accordion] Como sei o id do saque que pedi? > > A criação responde `201` sem corpo. Liste `GET /v1/payout-requests` com o `merchantId` da sua conta: a lista vem do mais recente para o mais antigo. > [accordion] Por que o saldo vem também em USD? > > O objeto `usdBalance` traz os mesmos três valores convertidos para dólar, o que ajuda a ver o total numa base única. > [accordion] Posso usar a mesma chave secreta nas três rotas? > > Sim. As três usam Basic com a chave secreta. Só confirme que a chave não foi gerada por um usuário com perfil Desenvolvedor, que não acessa saldo nem saques. ## Como testar | Código | Cenário | O que comprovar | | - | - | - | | PAY-01 | Consultar o saldo antes do saque | `GET /v1/wallets` com `merchantId` devolve o saldo por moeda e `isWithdrawalEnabled` | | PAY-02 | Montar o saque via Pix | Corpo com `merchantId`, `amount` em reais, `currency` `BRL` e `externalAccountDetails.type` `pix`; `201` sem corpo tratado, com o `id` buscado na listagem | | PAY-03 a PAY-05 | Saldo insuficiente, limite e saque pendente | Tratamento dos `422` correspondentes | | PAY-06 | Acompanhar o status | Leitura de `pending`, `approved` e `rejected` na listagem | | PAY-07 | Valor em reais | O fluxo envia o valor em reais | Como não existe saque no Modo Teste, os cenários de saque são conferidos no código e na montagem da requisição. Detalhes no [roteiro de homologação](/homologacao/roteiro). A consulta de meios de pagamento também é a forma mais simples de validar a chave, como mostrado em [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes). ## Veja também > [card] [Listar carteiras](/referencia/carteiras/listar) > > Contrato completo de GET /v1/wallets. > [card] [Solicitar saque](/referencia/saques/criar) > > Contrato completo de POST /v1/payout-requests. > [card] [Listar saques](/referencia/saques/listar) > > Filtros e status dos saques. > [card] [Listar meios de pagamento](/referencia/meios-de-pagamento/listar) > > Contrato completo de GET /v1/payment-methods. # Webhooks de assinatura Source: https://docs.fastpaybrasil.com/guias/webhooks/assinatura Eventos de criação, ativação, renovação, falha de pagamento, cancelamento e expiração das assinaturas recorrentes. As assinaturas cobram o cliente sozinhas, a cada ciclo, sem ninguém na tela. Os webhooks de assinatura são a forma de o seu sistema acompanhar isso: quando a assinatura começa, quando renova, quando uma cobrança falha e quando ela termina. > [!NOTE] > > **Para o negócio:** estes eventos mantêm o acesso do assinante coerente com o pagamento. `subscription.renewed` estende o acesso, `subscription.payment_failed` é a hora de avisar o cliente para trocar o cartão e `subscription.expired` encerra o acesso quando as tentativas de cobrança se esgotam. Também é por eles que a sua régua de comunicação (boas-vindas, aviso de falha, oferta de reativação) pode ser disparada automaticamente. ## Quando usar | Situação | Evento | | - | - | | Liberar o serviço e enviar boas-vindas | `subscription.activated` | | Estender o acesso por mais um período | `subscription.renewed` | | Avisar o cliente sobre cartão recusado | `subscription.payment_failed` | | Encerrar o acesso após cancelamento | `subscription.cancelled` | | Encerrar o acesso após esgotar as retentativas ou fim do plano | `subscription.expired` | | Registrar a assinatura no seu CRM | `subscription.created` | | Saber que a primeira cobrança em análise foi aprovada | `subscription.activated` (a assinatura sai de `pending_activation`) | ## Como funciona O desenho abaixo mostra o que o seu sistema faz ao receber cada evento de assinatura. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart LR E1[["subscription.created"]]:::evento E2[["subscription.activated"]]:::evento E3[["subscription.renewed"]]:::evento E4[["subscription.payment_failed"]]:::evento E5[["subscription.cancelled"]]:::evento E6[["subscription.expired"]]:::evento A1["Registre a assinatura
no seu CRM"]:::lojista A2["Libere o acesso e
envie as boas-vindas"]:::ok A3["Estenda o acesso até
current_period_end"]:::ok A4["Avise o cliente, com
controle de frequência
status continua active"]:::alerta Q5{"cancellation_type?"}:::decisao A5a["regret: revogue já
refunded indica o estorno"]:::erro A5b["regular: mantenha até
current_period_end"]:::neutro A6["Revogue o acesso e
ofereça reativação"]:::erro E1 --> A1 E2 --> A2 E3 --> A3 E4 --> A4 E5 --> Q5 Q5 -->|"até 7 dias"| A5a Q5 -->|"depois de 7 dias"| A5b E6 --> A6 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Cada cobrança de assinatura paga também gera `charge.created` e `charge.paid`. A recusa gera só o `subscription.payment_failed`. **1. Assinatura criada** Sua aplicação chama `POST /v1/subscriptions`. A Finvia envia `subscription.created`. **2. Ativação** Com a primeira cobrança aprovada (ou o início do trial), chega `subscription.activated`. **3. Renovações** A cada ciclo cobrado com sucesso, chega `subscription.renewed`, com o número do ciclo em `charge.billing_cycle`. **4. Falhas e retentativas** Se a cobrança de renovação falhar, cada tentativa malsucedida gera um `subscription.payment_failed`. A assinatura continua `active` enquanto houver tentativas. **5. Encerramento** Com o cancelamento chega `subscription.cancelled`. Com as tentativas esgotadas ou o fim do plano chega `subscription.expired`. ## Eventos disponíveis | Evento | Quando é enviado | | - | - | | `subscription.created` | Uma nova assinatura é criada | | `subscription.activated` | A assinatura é ativada (primeira cobrança bem-sucedida; em planos com trial, inclui a ativação em trial) | | `subscription.renewed` | Uma cobrança recorrente é processada com sucesso (inclui a primeira cobrança cheia depois do trial) | | `subscription.payment_failed` | **Cada tentativa** de cobrança recorrente que falha | | `subscription.cancelled` | A assinatura é cancelada | | `subscription.expired` | A assinatura é encerrada (limite de retentativas esgotado ou plano chegou ao `endDate`) | > [!NOTE] > > Os eventos `subscription.trial_started` e `subscription.trial_ended` estão definidos no contrato de tipos, mas **não são entregues atualmente**. Não os implemente como ativos. Em planos com trial, acompanhe a ativação e a conversão pelos eventos `subscription.activated` e `subscription.renewed`, que trazem o objeto `trial` no payload. ## Status da assinatura | Valor | Significado | | - | - | | `pending_activation` | A primeira cobrança foi recusada ou está em análise. A assinatura não está ativa, não cobra e não renova. Se a análise aprovar o pagamento, ela passa a `active` automaticamente | | `active` | Ativa e em dia. Continua `active` durante as retentativas de cobrança | | `cancelled` | Cancelada | | `expired` | Encerrada: limite de retentativas esgotado ou plano chegou ao `endDate` | ## Regras de negócio | Regra | Detalhe | | - | - | | Retentativa de renovação | Nas rodadas de cobrança das 06h, 12h e 18h (horário de Brasília), até o limite de tentativas recusadas no ciclo descrito em [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida) | | Aviso de falha | Cada tentativa que falha gera um `subscription.payment_failed` | | Fim das tentativas | Atingido o limite, a assinatura vira `expired` e chega `subscription.expired` | | Primeira cobrança recusada | Gera `subscription.payment_failed` e a assinatura fica em `pending_activation`, sem nova tentativa automática | | Fim do plano | Um plano com `endDate` também encerra a assinatura em `expired` | | Trial grátis | A cobrança de validação de R\$ 1,00 e o estorno dela **não geram webhooks** | | Formato | Envelope padrão com campos em **snake\_case**. Exceções: o objeto `trial` usa camelCase e `metadata` volta como foi enviada | | Valores | Em reais: `99.9` é R\$ 99,90 | | Destinos | Endpoints da conta dona da assinatura e endpoints da conta master com a opção de incluir subcontas. Assinaturas não têm `postbackUrl`. Veja [Quem recebe cada evento](/guias/webhooks/visao-geral#quem-recebe-cada-evento) | | Entrega | Veja [Entrega e retentativas](/guias/webhooks/visao-geral#entrega-e-retentativas) | > [!WARNING] > > Um cliente com cartão recusado pode gerar vários eventos `subscription.payment_failed` no mesmo ciclo, até três por dia. Se a sua aplicação envia um e-mail por evento, o cliente recebe vários e-mails em poucos dias. Controle a frequência dos avisos do seu lado, por exemplo um aviso por dia ou só na primeira e na última tentativa. ### Relação com os webhooks de cobrança Cada cobrança de assinatura **paga** também dispara os webhooks `charge.created` e `charge.paid` da cobrança correspondente. A **recusa** de uma cobrança de assinatura **não** dispara webhook `charge.*` de recusa: quem avisa é o `subscription.payment_failed`. Para ligar os dois fluxos: * Nos eventos de assinatura, `data.charge.charge_id` é o **ID da cobrança**, o mesmo usado nos webhooks `charge.*` e em `GET /v1/charges/{id}`. Já `data.charge.id` é o ID do registro de cobrança da assinatura, outro identificador. * No webhook `charge.paid` de uma cobrança de assinatura, o `metadata` traz `subscription_id` e `billing_cycle`, o que permite a ligação no sentido inverso. > [!TIP] > > **Para o desenvolvedor:** se você trata `charge.paid` e `subscription.renewed`, o mesmo pagamento chega duas vezes por caminhos diferentes. Escolha um deles como referência para estender o acesso (o `subscription.renewed` é o mais direto) e use o outro só para conciliação financeira, evitando estender o acesso duas vezes. ## Envelope Todos os webhooks de assinatura usam o envelope padrão, com campos em snake\_case. O `id` da raiz identifica o evento e é a chave da [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos). Não use `livemode` para separar teste de produção: as assinaturas não têm modo de teste. ```json theme={null} { "id": "evt_7RtY2uI5oP8aS1dF4gH6jK9l", "event": "subscription.activated", "livemode": true, "data": { "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2", "object": "subscription", "status": "active" } } ``` ### Campos base do objeto `data` Presentes em todos os eventos: | Campo | Tipo | Descrição | | - | - | - | | `id` | string | ID da assinatura | | `object` | string | Sempre `"subscription"` | | `status` | string | Status atual | | `merchant_id` | string | ID do merchant | | `customer` | object | Dados do cliente | | `plan` | object | Dados do plano | | `current_period_start` | string \| null | Início do período atual (ISO 8601) | | `current_period_end` | string \| null | Fim do período atual (ISO 8601) | | `metadata` | object \| null | Metadados enviados por você | | `created_at` | string | Data e hora de criação (ISO 8601) | | `updated_at` | string | Data e hora da última atualização (ISO 8601) | Em planos com trial, `subscription.activated` e `subscription.renewed` trazem também o objeto `trial`, com `startDate`, `endDate` e, depois da conversão, `convertedAt`. Esse objeto usa camelCase, diferente do resto do payload. `metadata` volta exatamente como você enviou. ### Objeto `customer` ```json theme={null} { "id": "cu_abc123", "name": "Joao Silva", "email": "joao@email.com", "document_id": "52998224725" } ``` ### Objeto `plan` Valores em **reais** (ex.: `99.9` para R\$ 99,90): ```json theme={null} { "id": "plan_abc123", "name": "Plano Mensal", "price": 99.9, "currency": "BRL", "recurrence_type": "monthly" } ``` ### Objeto `charge` Presente em `subscription.renewed` e `subscription.payment_failed`, e em `subscription.activated` **exceto no trial grátis** (não há cobrança na ativação). Valores em reais. | Campo | Tipo | Descrição | | - | - | - | | `id` | string | ID do registro de cobrança da assinatura (diferente do ID usado nos webhooks `charge.*`) | | `charge_id` | string \| null | **ID da cobrança**, o mesmo dos webhooks `charge.*` e de `GET /v1/charges/{id}` | | `billing_cycle` | integer | Número do ciclo de cobrança | | `amount` | number | Valor em reais | | `currency` | string | Moeda | | `status` | string | Status da cobrança | | `spread` | number \| null | Spread aplicado (em `activated` e `renewed`) | | `net` | number \| null | Valor líquido em reais (em `activated` e `renewed`) | | `is_trial_charge` | boolean | `true` se é a cobrança do trial (em `activated` e `renewed`) | | `failure_reason` | string \| null | Motivo da falha (em `payment_failed`) | | `created_at` | string | Data e hora da cobrança (ISO 8601) | ## Payloads por evento ### subscription.created Enviado logo após a criação da assinatura. Traz só os campos base. ```json theme={null} { "id": "evt_3NcV8bX1zL5kJ7hG2fD9sA4q", "event": "subscription.created", "livemode": true, "data": { "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2", "object": "subscription", "status": "active", "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "customer": { "id": "cu_abc123", "name": "Joao Silva", "email": "joao@email.com", "document_id": "52998224725" }, "plan": { "id": "plan_abc123", "name": "Plano Mensal", "price": 99.9, "currency": "BRL", "recurrence_type": "monthly" }, "current_period_start": "2024-01-15T10:30:00.000Z", "current_period_end": "2024-02-15T10:30:00.000Z", "metadata": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" } } ``` ### subscription.activated Enviado quando a assinatura é ativada. O conteúdo muda conforme o plano: | Tipo de plano | Quando chega | Objeto `charge` | Objeto `trial` | | - | - | - | - | | Sem trial | Após a primeira cobrança aprovada | Sim, com `billing_cycle: 1` | Não | | Trial pago | Após a cobrança do trial | Sim, com `is_trial_charge: true` e `billing_cycle: 0` | Sim | | Trial grátis | Na criação | **Não** (não há cobrança) | Sim | ```json theme={null} { "id": "evt_7RtY2uI5oP8aS1dF4gH6jK9l", "event": "subscription.activated", "livemode": true, "data": { "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2", "object": "subscription", "status": "active", "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "customer": { "id": "cu_abc123", "name": "Joao Silva", "email": "joao@email.com", "document_id": "52998224725" }, "plan": { "id": "plan_abc123", "name": "Plano Mensal", "price": 99.9, "currency": "BRL", "recurrence_type": "monthly" }, "current_period_start": "2024-01-15T10:30:00.000Z", "current_period_end": "2024-02-15T10:30:00.000Z", "metadata": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:05.000Z", "charge": { "id": "subchg_abc123", "charge_id": "2RhQg9M7ZCg3X3nMb9W2kY9R", "billing_cycle": 1, "amount": 99.9, "currency": "BRL", "spread": 3, "net": 96.9, "status": "paid", "is_trial_charge": false, "created_at": "2024-01-15T10:30:00.000Z" } } } ``` ### subscription.renewed Enviado quando uma cobrança recorrente é processada com sucesso. A estrutura é igual à do `subscription.activated`, com `billing_cycle` incrementado. ```json theme={null} { "id": "evt_4WqE6rT9yU2iO5pA8sD1fG3h", "event": "subscription.renewed", "livemode": true, "data": { "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2", "object": "subscription", "status": "active", "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "customer": { "id": "cu_abc123", "name": "Joao Silva", "email": "joao@email.com", "document_id": "52998224725" }, "plan": { "id": "plan_abc123", "name": "Plano Mensal", "price": 99.9, "currency": "BRL", "recurrence_type": "monthly" }, "current_period_start": "2024-02-15T10:30:00.000Z", "current_period_end": "2024-03-15T10:30:00.000Z", "metadata": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-02-15T10:30:05.000Z", "charge": { "id": "subchg_def456", "charge_id": "2vXa7Bq4Nm1Kc8Lp3Zr6Td9Wf5", "billing_cycle": 2, "amount": 99.9, "currency": "BRL", "spread": 3, "net": 96.9, "status": "paid", "is_trial_charge": false, "created_at": "2024-02-15T10:30:00.000Z" } } } ``` ### subscription.payment\_failed Enviado a **cada tentativa** de cobrança recorrente que falha. Traz `failure_reason` no topo de `data` e o objeto `charge` com os detalhes da falha. ```json theme={null} { "id": "evt_8ZxC1vB4nM7qW2eR5tY9uI6o", "event": "subscription.payment_failed", "livemode": true, "data": { "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2", "object": "subscription", "status": "active", "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "customer": { "id": "cu_abc123", "name": "Joao Silva", "email": "joao@email.com", "document_id": "52998224725" }, "plan": { "id": "plan_abc123", "name": "Plano Mensal", "price": 99.9, "currency": "BRL", "recurrence_type": "monthly" }, "current_period_start": "2024-02-15T10:30:00.000Z", "current_period_end": "2024-03-15T10:30:00.000Z", "metadata": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-02-15T10:30:05.000Z", "failure_reason": "Recusa do banco emissor", "charge": { "id": "subchg_ghi789", "charge_id": "2kEs4Hu7Jy0Ob3Ni6Mt9Pq2Rw8", "billing_cycle": 2, "amount": 99.9, "currency": "BRL", "status": "failed", "failure_reason": "Recusa do banco emissor", "created_at": "2024-02-15T10:30:00.000Z" } } } ``` > [!NOTE] > > `failure_reason` é um texto descritivo (ex.: `"Recusa do banco emissor"`, `"Cartão vencido"`). Use-o para exibir ou registrar, nunca para decidir o fluxo. `charge.charge_id` vem `null` só quando a tentativa nem chegou a ser enviada para cobrança (cartão vencido ou indisponível). Essa tentativa também conta para o limite de tentativas do ciclo. ### subscription.cancelled Enviado quando a assinatura é cancelada. Traz `cancelled_at`, `cancellation_type` e `refunded`. > [tab] Arrependimento (até 7 dias) > > ```json theme={null} > { > "id": "evt_9MnB3vC6xZ1aS4dF7gH2jK5l", > "event": "subscription.cancelled", > "livemode": true, > "data": { > "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2", > "object": "subscription", > "status": "cancelled", > "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", > "customer": { > "id": "cu_abc123", > "name": "Joao Silva", > "email": "joao@email.com", > "document_id": "52998224725" > }, > "plan": { > "id": "plan_abc123", > "name": "Plano Mensal", > "price": 99.9, > "currency": "BRL", > "recurrence_type": "monthly" > }, > "current_period_start": "2024-01-15T10:30:00.000Z", > "current_period_end": "2024-02-15T10:30:00.000Z", > "metadata": null, > "created_at": "2024-01-15T10:30:00.000Z", > "updated_at": "2024-01-16T10:30:00.000Z", > "cancelled_at": "2024-01-16T10:30:00.000Z", > "cancellation_type": "regret", > "refunded": true > } > } > ``` > [tab] Regular (após 7 dias) > > ```json theme={null} > { > "id": "evt_6QaZ9wS2xE5dC8rF1vT4gB7y", > "event": "subscription.cancelled", > "livemode": true, > "data": { > "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2", > "object": "subscription", > "status": "cancelled", > "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", > "customer": { > "id": "cu_abc123", > "name": "Joao Silva", > "email": "joao@email.com", > "document_id": "52998224725" > }, > "plan": { > "id": "plan_abc123", > "name": "Plano Mensal", > "price": 99.9, > "currency": "BRL", > "recurrence_type": "monthly" > }, > "current_period_start": "2024-01-15T10:30:00.000Z", > "current_period_end": "2024-02-15T10:30:00.000Z", > "metadata": null, > "created_at": "2024-01-15T10:30:00.000Z", > "updated_at": "2024-01-20T10:30:00.000Z", > "cancelled_at": "2024-01-20T10:30:00.000Z", > "cancellation_type": "regular", > "refunded": false > } > } > ``` | Tipo | Condição | Estorno | Acesso | | - | - | - | - | | `regret` | Até 7 dias após a criação | Todas as cobranças pagas. `refunded: true` se todas foram estornadas; `false` se não havia cobrança paga (ex.: trial grátis) ou se um estorno falhou | Revogado imediatamente | | `regular` | Depois de 7 dias | Não há estorno (`refunded: false`) | Vale até o fim do período pago (controle da sua plataforma) | > [!NOTE] > > No cancelamento regular, o status já é `cancelled` e as próximas cobranças não acontecem. `current_period_end` indica até quando o acesso do comprador vale, e é a sua plataforma que controla o acesso até essa data. ### subscription.expired Enviado quando a assinatura é encerrada por esgotar as retentativas de cobrança ou porque o plano chegou ao `endDate`. Traz só os campos base. ```json theme={null} { "id": "evt_5PlK8jH2gF6dS9aQ3wE7rT1y", "event": "subscription.expired", "livemode": true, "data": { "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2", "object": "subscription", "status": "expired", "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "customer": { "id": "cu_abc123", "name": "Joao Silva", "email": "joao@email.com", "document_id": "52998224725" }, "plan": { "id": "plan_abc123", "name": "Plano Mensal", "price": 99.9, "currency": "BRL", "recurrence_type": "monthly" }, "current_period_start": "2024-01-15T10:30:00.000Z", "current_period_end": "2024-02-15T10:30:00.000Z", "metadata": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-02-20T10:30:00.000Z" } } ``` ## Ciclo de vida em eventos O desenho abaixo mostra os status da assinatura e o evento que acompanha cada mudança. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB NEW(["Nova assinatura
POST /v1/subscriptions"]):::lojista PA["pending_activation
1ª cobrança recusada
ou em análise"]:::alerta ACT["active
ativa e em dia"]:::ok REN[["subscription.renewed
a cada ciclo cobrado
continua active"]]:::evento FAL[["subscription.payment_failed
a cada tentativa que falha
continua active"]]:::evento CAN["cancelled
cancelada, estado final"]:::neutro EXP["expired
encerrada, estado final"]:::erro NEW -->|"created + activated"| ACT NEW -->|"created, e payment_failed
se a 1ª foi recusada"| PA PA -->|"análise aprova
activated"| ACT ACT -.-> REN ACT -.-> FAL ACT -->|"cancelamento
cancelled"| CAN ACT -->|"tentativas esgotadas
ou endDate · expired"| EXP classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Nos rótulos das setas, os eventos aparecem sem o prefixo `subscription.`. | De | Para | Evento | | - | - | - | | (nova) | `active` | `subscription.created` e `subscription.activated` | | (nova) | `pending_activation` | `subscription.created` e, se a primeira cobrança foi recusada, `subscription.payment_failed` | | `pending_activation` | `active` | `subscription.activated`, quando a análise aprova a primeira cobrança | | `active` | `active` | `subscription.renewed` | | `active` | `active` | `subscription.payment_failed` (o status continua `active`) | | `active` | `cancelled` | `subscription.cancelled` | | `active` | `expired` | `subscription.expired` | `cancelled` e `expired` são estados finais. Para o cliente voltar, crie uma nova assinatura. Uma assinatura em `pending_activation` também não é cobrada de novo: para tentar outra vez, crie uma nova assinatura e, se quiser, cancele a pendente. ## Passo a passo ```javascript Node.js theme={null} app.post('/webhooks/finvia', async (req, res) => { const { event, data } = req.body; res.status(200).send('OK'); switch (event) { case 'subscription.created': await crm.registerSubscription(data.id, data.customer.email); break; case 'subscription.activated': // Liberar acesso e enviar boas-vindas await access.grant(data.id, data.current_period_end); if (data.trial) { // Assinatura em trial: data.trial.endDate indica quando a primeira cobrança cheia acontece } break; case 'subscription.renewed': // Estender o acesso até o fim do novo período await access.extend(data.id, data.current_period_end, data.charge.billing_cycle); break; case 'subscription.payment_failed': // Avisar o cliente (controle a frequência do seu lado) // Não há troca de cartão: oriente a cancelar e criar outra assinatura await notify.paymentFailed(data.customer.email, data.failure_reason); break; case 'subscription.cancelled': if (data.cancellation_type === 'regret') { // data.refunded indica se as cobranças pagas foram estornadas // (false quando não havia cobrança paga, como no trial grátis) await access.revokeNow(data.id); } else { // Manter o acesso até data.current_period_end await access.revokeAt(data.id, data.current_period_end); } break; case 'subscription.expired': await access.revokeNow(data.id); // Enviar oferta de reativação break; default: console.log(`Evento não tratado: ${event}`); } }); ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Código esperando `subscription.trial_started` nunca dispara | Esse evento não é entregue atualmente | Use `subscription.activated` e `subscription.renewed` com o objeto `trial` | | Cobrança da assinatura não encontrada em `GET /v1/charges/{id}` | Consulta feita com `data.charge.id`, que é o ID do registro de cobrança da assinatura | Use `charge_id` para consultar a cobrança | | Acesso estendido duas vezes no mesmo ciclo | Tratamento de `charge.paid` e `subscription.renewed` para o mesmo pagamento | Escolha um único evento como referência para o acesso | | Esperando `charge.*` de recusa na renovação | A recusa de assinatura só gera `subscription.payment_failed` | Trate `subscription.payment_failed` | | Erro ao ler `charge` no trial grátis | O `subscription.activated` do trial grátis não tem `charge` | Verifique se `data.charge` existe antes de ler | | Lógica baseada em `failure_reason` falha | O campo é texto livre, não código | Use-o só para exibir ou registrar | ## Perguntas frequentes > [accordion] O cliente teve o cartão recusado. A assinatura é cancelada imediatamente? > > Não. Ela continua `active` enquanto houver retentativas, nas rodadas das 06h, 12h e 18h (horário de Brasília), até o limite descrito em [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida). Se todas falharem, ela vira `expired` e chega `subscription.expired`. > [accordion] Como o cliente troca o cartão de uma assinatura? > > Não existe troca de cartão na assinatura. O caminho é cancelar a assinatura atual e criar outra com o novo cartão. A nova começa um ciclo novo, com cobrança imediata. Veja [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida). > [accordion] A validação de R\$ 1,00 do trial grátis gera webhook? > > Não. A cobrança de validação e o estorno dela não geram webhooks. No trial grátis, o `subscription.activated` chega na criação, sem o objeto `charge`. > [accordion] Até quando mantenho o acesso depois de um cancelamento regular? > > Até `current_period_end`. O status já é `cancelled` e as cobranças pararam, mas o período pago continua valendo. Quem controla o acesso até essa data é a sua plataforma. > [accordion] Como sei de qual assinatura veio um charge.paid? > > O `metadata` do `charge.paid` de uma cobrança de assinatura traz `subscription_id` e `billing_cycle`. ## Como testar > [!WARNING] > > Assinaturas não têm sandbox: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). | Código | Cenário | O que comprovar | | - | - | - | | SUB-04 | Criar assinatura | Status `active` e primeira cobrança processada | | SUB-05 | Receber `subscription.created` e `subscription.activated` | Eventos recebidos e respondidos com `2xx` | | SUB-06 | Cancelar em até 7 dias | `cancellationType: "regret"`, `refunded: true` e webhook `subscription.cancelled` | ## Veja também > [card] [Assinaturas: visão geral](/guias/assinaturas/visao-geral) > > Como a cobrança recorrente funciona. > [card] [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida) > > Status, retentativa e cancelamento. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Os eventos charge.\* de cada cobrança. > [card] [Webhooks: visão geral](/guias/webhooks/visao-geral) > > Destinos, formatos, entrega e deduplicação. # Webhooks de cobrança Source: https://docs.fastpaybrasil.com/guias/webhooks/cobranca Eventos do ciclo de vida da cobrança: criação, espera, pagamento, recusa, estorno, pré-chargeback, bloqueio e o postback legado charge.updated. Os webhooks de cobrança avisam o seu sistema a cada passo de uma cobrança (charge): quando ela é criada, quando aguarda pagamento, quando é paga, recusada ou estornada, e quando entra em disputa. O postback legado `charge.updated`, entregue só ao `postbackUrl`, complementa esses eventos com recusas assíncronas e com o chargeback formalizado. > [!NOTE] > > **Para o negócio:** `charge.paid` é o sinal para liberar o pedido, `charge.refunded` é o sinal para registrar a devolução e `charge.blocked` avisa que uma venda entrou em análise de disputa. O chargeback formalizado chega pelo `charge.updated`, no `postbackUrl`, e, quando o valor é revertido do saldo, também como `charge.refunded`. Se a sua operação vende com Pix, o `charge.paid` é a forma automática de saber que o cliente pagou. ## Quando usar | Situação | Evento que importa | | - | - | | Liberar pedido ou acesso após o pagamento | `charge.paid` | | Mostrar "aguardando pagamento" no painel do lojista | `charge.created` e `charge.pending` | | Registrar uma recusa no seu sistema | Resposta de `POST /v1/charges` e, de forma complementar, `charge.refused` ou `charge.failed` | | Registrar a devolução no financeiro | `charge.refunded` | | Marcar o pedido como em disputa | `charge.pre_chargeback` (alerta) e `charge.blocked` (bloqueio por MED ou chargeback em análise) | | Registrar o chargeback formalizado | `charge.updated` com `status: "chargeback"`, no `postbackUrl` | ## Como funciona O desenho abaixo mostra quais eventos saem da criação da cobrança até o pagamento ou a recusa. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB POST(["Sua aplicação chama
POST /v1/charges"]):::lojista CR[["charge.created
sempre, na criação"]]:::evento RES{"Como terminou
a criação?"}:::decisao PEN["pending
ex.: Pix gerado"]:::alerta AN["in_analysis
análise antifraude"]:::alerta AUT["authentication_required
3DS gerenciado"]:::alerta REC["refused ou failed"]:::erro EPEN[["charge.pending"]]:::evento PAID["paid
pagamento confirmado"]:::ok EPAID[["charge.paid
com paid_at"]]:::evento EREC[["charge.refused
ou charge.failed"]]:::evento ASY["Recusa informada depois
pelo adquirente: negada,
cancelada ou expirada"]:::erro UPD[["Só charge.updated
na postbackUrl"]]:::evento POST --> CR --> RES RES --> AN RES --> PEN RES -->|"aprovada na hora"| PAID RES --> AUT RES -->|"recusada"| REC PEN --> EPEN PEN -->|"comprador paga"| PAID AN -->|"aprovada"| PAID AUT -->|"autenticou"| PAID AUT -->|"3DS termina
em recusa"| REC PAID --> EPAID REC --> EREC PEN -->|"cancelado
ou expirado"| ASY AN -->|"negada"| ASY ASY --> UPD classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 ``` Os eventos do envelope padrão vão aos endpoints e à `postbackUrl`. O `charge.updated` vai só à `postbackUrl` e também sai em outras situações, como o pagamento de um Pix. **1. A cobrança é criada** Sua aplicação chama `POST /v1/charges`. A resposta síncrona traz o `id`, o `status` e, no Pix, o QR Code. **2. Eventos da criação** A Finvia envia `charge.created`. Se o processamento termina em `pending` (por exemplo, Pix gerado), envia também `charge.pending`. Se a cobrança é recusada ou falha na criação, envia `charge.refused` ou `charge.failed`. **3. Pagamento confirmado** Quando o pagamento é confirmado, na hora ou depois, chega `charge.paid` com `paid_at` preenchido. **4. Pós-venda** Estorno concluído gera `charge.refunded`. Alerta de pré-chargeback gera `charge.pre_chargeback`. Bloqueio da cobrança gera `charge.blocked`. Quem informou `postbackUrl` recebe ainda o `charge.updated` legado nas situações descritas em [Postback legado](#postback-legado). ## Eventos disponíveis | Evento | Quando é enviado | Destinos | | - | - | - | | `charge.created` | A cobrança foi criada | Endpoints e `postbackUrl` | | `charge.pending` | O processamento terminou em `pending` (ex.: Pix com QR Code gerado) | Endpoints e `postbackUrl` | | `charge.paid` | O pagamento foi confirmado, na hora ou depois, pelo adquirente | Endpoints e `postbackUrl` | | `charge.refused` | A cobrança foi recusada na criação ou ao final do 3DS gerenciado | Endpoints e `postbackUrl` | | `charge.failed` | A cobrança falhou na criação ou ao final do 3DS gerenciado | Endpoints e `postbackUrl` | | `charge.refunded` | O estorno foi concluído, inclusive o estorno feito no alerta de pré-chargeback e a reversão de saldo de um chargeback | Endpoints e `postbackUrl` | | `charge.pre_chargeback` | Um alerta de pré-chargeback foi registrado | Endpoints e `postbackUrl` | | `charge.blocked` | A cobrança foi bloqueada (MED ou chargeback em análise) | Endpoints e `postbackUrl` | | `charge.updated` | Postback legado: mudança de status informada pelo adquirente, fim do 3DS gerenciado com recusa ou falha, bloqueio e alerta de pré-chargeback | Só `postbackUrl` | Os endpoints que recebem cada evento seguem a regra da conta dona da cobrança, explicada em [Quem recebe cada evento](/guias/webhooks/visao-geral#quem-recebe-cada-evento). Uma cobrança que fica em `in_analysis` ou `authentication_required` na criação gera só o `charge.created`. O evento seguinte depende do desfecho. ## Status da cobrança O campo `status` dentro de `data` pode ter estes valores: | Valor | Significado | | - | - | | `pending` | Aguardando pagamento | | `paid` | Pago com sucesso. Continua `paid` durante um bloqueio | | `refused` | Recusado | | `failed` | Falha no processamento | | `refunded` | Estornado | | `in_analysis` | Enviado para revisão manual pela análise antifraude | | `authentication_required` | Aguardando o comprador concluir a autenticação no endereço de `authenticationUrl` | | `pre_chargeback` | Alerta de pré-chargeback registrado (veja [Pré-chargeback](#pré-chargeback)) | | `chargeback` | Chargeback formalizado (veja [Chargeback formalizado](#chargeback-formalizado)) | A tabela completa, com o que fazer em cada status, está em [Status de cobrança](/anexos/status-de-cobranca). ## Regras de negócio | Regra | Detalhe | | - | - | | Formato de nomes | O envelope padrão usa **snake\_case** no primeiro nível de `data` (`psp_ref_id`, `paid_at`) e camelCase dentro dos objetos aninhados. O `charge.updated` usa **camelCase** em todos os níveis. Veja [Formato por família](/guias/webhooks/visao-geral#formato-por-família) | | Valores | Em reais: `100` significa R\$ 100,00 | | `charge.updated` | Vai **somente** ao `postbackUrl`. Os endpoints nunca recebem esse evento | | Recusa síncrona | Volta na resposta de `POST /v1/charges` e também em `charge.refused` ou `charge.failed`, no máximo uma vez por cobrança. A resposta continua sendo a fonte principal | | Recusa assíncrona | Recusa ou falha informada depois pelo adquirente gera só o `charge.updated` no `postbackUrl` | | Motivo da recusa | O envelope padrão não traz o motivo. Ele aparece em `GET /v1/charges/{id}` e no `charge.updated` | | Recusa em assinatura | A cobrança recorrente recusada gera `subscription.payment_failed` e não gera `charge.refused` nem `charge.failed` | | Teste e produção | Cobranças de teste chegam com `livemode: false` e `data.is_test: true` nos mesmos endpoints | | Entrega | Veja [Entrega e retentativas](/guias/webhooks/visao-geral#entrega-e-retentativas) | > [!WARNING] > > O status `chargeback` e as recusas assíncronas só chegam pelo `charge.updated`. Os endpoints recebem, no chargeback, apenas o `charge.refunded`, e só quando o valor é revertido do saldo. Se a sua operação precisa desses avisos, **informe `postbackUrl` em todas as cobranças**. Sem ele, confirme o estado das cobranças em disputa ou em análise com `GET /v1/charges/{id}`. ## Envelope padrão Todos os eventos de cobrança, exceto o `charge.updated`, usam o envelope padrão: ```json theme={null} { "id": "evt_1XcN7hJ4uQ2pZ8eL6wS3kF9a", "event": "charge.paid", "livemode": true, "data": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "paid" } } ``` O `id` da raiz identifica o evento: cada evento tem o seu, e é ele que a [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos) usa. `livemode` é `false` em cobranças de teste. O objeto `data` traz a cobrança (o exemplo acima foi resumido). ### Campos do objeto `data` | Campo | Tipo | Descrição | | - | - | - | | `id` | string | ID da cobrança. É o mesmo usado em `GET /v1/charges/{id}` | | `status` | string | Status atual (veja a tabela de status) | | `psp_ref_id` | string \| null | ID de referência no processador de pagamento | | `amount` | number | Valor bruto, em reais | | `currency` | string | Código ISO da moeda (ex.: `BRL`) | | `spread` | number | Spread aplicado | | `anticipation_fee_estimated` | number | Taxa de antecipação estimada (cartão de crédito; `0` para os outros meios) | | `net` | number | Valor líquido, em reais | | `customer` | object \| null | Dados do cliente | | `payment_method` | object | Dados do meio de pagamento, com chaves internas em camelCase | | `merchant_id` | string | ID da conta dona da cobrança. Em eventos de subconta recebidos pela master, é o id da subconta | | `payment_details` | object \| null | Detalhes adicionais. No Pix, traz `endToEndId`, `copyPaste` e `qrCodeBase64` (chaves internas em camelCase) | | `shipping_address` | object \| null | Endereço de entrega, com chaves internas em camelCase | | `tracking_info` | object \| null | Informações de rastreio, com chaves internas em camelCase | | `three_ds` | object \| null | Dados da autenticação 3D Secure, com chaves internas em camelCase | | `freight_details` | object \| null | Dados de frete, com chaves internas em camelCase | | `metadata` | object \| null | Metadados enviados por você na criação, com as chaves exatamente como foram enviadas | | `postback_url` | string \| null | URL de postback informada na cobrança | | `paid_at` | string \| null | Data e hora do pagamento (ISO 8601) | | `is_test` | boolean \| null | `true` se a cobrança é de teste | | `is_blocked`, `blocked_at`, `blocked_reason` | | Dados do bloqueio, presentes no `charge.blocked`. Veja [Bloqueio](#bloqueio) | | `chargeback_alert_refunded` | boolean | `true` no `charge.refunded` gerado pelo estorno de um alerta de pré-chargeback | | `created_at` | string | Data e hora de criação (ISO 8601) | | `updated_at` | string | Data e hora da última atualização (ISO 8601) | | `deleted_at` | string \| null | Data e hora de exclusão, se houver | > [!TIP] > > **Para o desenvolvedor:** use `paid_at` como data oficial do pagamento na sua conciliação. O webhook pode chegar bem depois do pagamento. ### Objeto `customer` ```json theme={null} { "id": "cu_abc123", "name": "Joao Silva", "email": "joao@email.com", "document": { "id": "52998224725", "type": "cpf" }, "phone": "+5511987654321" } ``` ### Objeto `payment_method` As chaves internas ficam em camelCase, no formato em que foram gravadas: > [tab] Cartão de crédito > > ```json theme={null} > { > "type": "credit_card", > "installments": 3, > "holderName": "JOAO SILVA", > "expirationMonth": "12", > "expirationYear": "2030", > "firstSix": "411111", > "lastFour": "1111" > } > ``` > [tab] Pix > > No Pix, o objeto contém apenas o tipo. Os dados do QR Code ficam em `payment_details`. > > ```json theme={null} > { "type": "pix" } > ``` ### Objeto `payment_details` (Pix) A chave externa é `payment_details` (snake\_case), mas os campos **internos** são camelCase, no mesmo formato da resposta da API: ```json theme={null} { "endToEndId": "E12345678202401151035abcdef123456", "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." } ``` | Campo | Tipo | Descrição | | - | - | - | | `endToEndId` | string | Identificador End to End do Pix | | `copyPaste` | string | Código Pix "copia e cola" (BR Code EMV) | | `qrCodeBase64` | string \| null | Imagem do QR Code (PNG, 256x256) em data URI, gerada a partir do `copyPaste`. Pode ser usada direto no `src` de uma tag `` | > [!NOTE] > > `qrCodeBase64` pode vir `null` ou ausente em cobranças criadas antes da introdução do campo ou quando a imagem não pôde ser gerada. Nesses casos, gere o QR Code a partir do `copyPaste`. ### Objeto `shipping_address` As chaves internas ficam em camelCase, como foram enviadas em `shippingAddress` na criação da cobrança. O país volta exatamente como foi enviado, no padrão ISO 3166-1 alpha-3 (envie em maiúsculas, como `BRA`). ```json theme={null} { "postalCode": "01310-100", "addressLine1": "Av. Paulista, 1000", "addressLine2": "Apto 42", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA" } ``` ### Objeto `tracking_info` ```json theme={null} { "trackingCode": "BR123456789BR", "shippingProvider": "Correios", "trackingUrl": "https://rastreamento.correios.com.br/...", "trackingStatus": "on_the_way" } ``` `trackingStatus` pode ser `awaiting_shipment`, `on_the_way` ou `delivered`. ## Payloads por evento > [tab] charge.created > > Enviado logo após a criação de uma nova cobrança. > > ```json theme={null} > { > "id": "evt_5TzWq1Lb8NcY2dR7kH4mX9vJ", > "event": "charge.created", > "livemode": true, > "data": { > "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "status": "pending", > "psp_ref_id": null, > "amount": 100, > "currency": "BRL", > "spread": 0, > "anticipation_fee_estimated": 0, > "net": 96.5, > "customer": { > "id": "cu_abc123", > "name": "Joao Silva", > "email": "joao@email.com", > "document": { "id": "52998224725", "type": "cpf" }, > "phone": null > }, > "payment_method": { "type": "pix" }, > "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", > "payment_details": { > "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD", > "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." > }, > "shipping_address": null, > "tracking_info": null, > "metadata": { "orderId": "ORD-123" }, > "postback_url": "https://meusite.com.br/webhooks/finvia", > "paid_at": null, > "is_test": false, > "created_at": "2024-01-15T10:30:00.000Z", > "updated_at": "2024-01-15T10:30:00.000Z", > "deleted_at": null > } > } > ``` > [tab] charge.pending > > Enviado quando o processamento termina em `pending` (por exemplo, Pix gerado). > > ```json theme={null} > { > "id": "evt_8GfK3sPq6VwD1yA9nE5rB2tM", > "event": "charge.pending", > "livemode": true, > "data": { > "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "status": "pending", > "psp_ref_id": "pix_ref_abc123", > "amount": 100, > "currency": "BRL", > "spread": 0, > "anticipation_fee_estimated": 0, > "net": 96.5, > "customer": { > "id": "cu_abc123", > "name": "Joao Silva", > "email": "joao@email.com", > "document": { "id": "52998224725", "type": "cpf" }, > "phone": null > }, > "payment_method": { "type": "pix" }, > "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", > "payment_details": { > "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD", > "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." > }, > "shipping_address": null, > "tracking_info": null, > "metadata": { "orderId": "ORD-123" }, > "postback_url": "https://meusite.com.br/webhooks/finvia", > "paid_at": null, > "is_test": false, > "created_at": "2024-01-15T10:30:00.000Z", > "updated_at": "2024-01-15T10:30:01.000Z", > "deleted_at": null > } > } > ``` > [tab] charge.paid > > Enviado quando o pagamento é confirmado. > > ```json theme={null} > { > "id": "evt_1XcN7hJ4uQ2pZ8eL6wS3kF9a", > "event": "charge.paid", > "livemode": true, > "data": { > "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "status": "paid", > "psp_ref_id": "pix_ref_abc123", > "amount": 100, > "currency": "BRL", > "spread": 1, > "anticipation_fee_estimated": 0, > "net": 95.5, > "customer": { > "id": "cu_abc123", > "name": "Joao Silva", > "email": "joao@email.com", > "document": { "id": "52998224725", "type": "cpf" }, > "phone": null > }, > "payment_method": { "type": "pix" }, > "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", > "payment_details": { > "endToEndId": "E12345678202401151035abcdef123456", > "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD", > "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." > }, > "shipping_address": null, > "tracking_info": null, > "metadata": { "orderId": "ORD-123" }, > "postback_url": "https://meusite.com.br/webhooks/finvia", > "paid_at": "2024-01-15T10:35:00.000Z", > "is_test": false, > "created_at": "2024-01-15T10:30:00.000Z", > "updated_at": "2024-01-15T10:35:00.000Z", > "deleted_at": null > } > } > ``` > [tab] charge.refused > > Enviado quando a cobrança é recusada na criação ou ao final do 3DS gerenciado. Em falha de processamento, o evento é `charge.failed`, com `status` `failed`. O motivo da recusa não vem no envelope: consulte `GET /v1/charges/{id}`. > > ```json theme={null} > { > "id": "evt_6KpZ2wQ9mT4rV7cX1bN8yL3s", > "event": "charge.refused", > "livemode": true, > "data": { > "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE", > "status": "refused", > "psp_ref_id": "card_ref_def456", > "amount": 599.7, > "currency": "BRL", > "spread": 0, > "anticipation_fee_estimated": 0, > "net": 0, > "customer": { > "id": "cu_def456", > "name": "Maria Souza", > "email": "maria@email.com", > "document": { "id": "52998224725", "type": "cpf" }, > "phone": null > }, > "payment_method": { > "type": "credit_card", > "installments": 3, > "holderName": "MARIA SOUZA", > "expirationMonth": "10", > "expirationYear": "2028", > "firstSix": "444433", > "lastFour": "1112" > }, > "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", > "payment_details": null, > "shipping_address": null, > "tracking_info": null, > "metadata": null, > "postback_url": null, > "paid_at": null, > "is_test": false, > "created_at": "2024-01-15T11:00:00.000Z", > "updated_at": "2024-01-15T11:00:02.000Z", > "deleted_at": null > } > } > ``` > [tab] charge.refunded > > Enviado depois que um estorno é concluído com sucesso. > > ```json theme={null} > { > "id": "evt_4MbR9dT2gY7vC1xK5qW8nP3h", > "event": "charge.refunded", > "livemode": true, > "data": { > "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "status": "refunded", > "psp_ref_id": "pix_ref_abc123", > "amount": 100, > "currency": "BRL", > "spread": 1, > "anticipation_fee_estimated": 0, > "net": 95.5, > "customer": { > "id": "cu_abc123", > "name": "Joao Silva", > "email": "joao@email.com", > "document": { "id": "52998224725", "type": "cpf" }, > "phone": null > }, > "payment_method": { "type": "pix" }, > "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", > "payment_details": { > "endToEndId": "E12345678202401151035abcdef123456", > "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD", > "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." > }, > "shipping_address": null, > "tracking_info": null, > "metadata": { "orderId": "ORD-123" }, > "postback_url": "https://meusite.com.br/webhooks/finvia", > "paid_at": "2024-01-15T10:35:00.000Z", > "is_test": false, > "created_at": "2024-01-15T10:30:00.000Z", > "updated_at": "2024-01-15T11:00:00.000Z", > "deleted_at": null > } > } > ``` > [tab] charge.blocked > > Enviado quando a cobrança é bloqueada (MED ou chargeback em análise). O status continua `paid`. > > ```json theme={null} > { > "id": "evt_9HqW3eR6tY1uI4oP7aS2dF5g", > "event": "charge.blocked", > "livemode": true, > "data": { > "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "status": "paid", > "amount": 100, > "currency": "BRL", > "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", > "payment_method": { "type": "pix" }, > "is_blocked": true, > "blocked_at": "2024-01-20T14:00:00.000Z", > "blocked_reason": "MED em análise", > "paid_at": "2024-01-15T10:35:00.000Z", > "is_test": false > } > } > ``` > > O exemplo foi resumido. O `data` traz os mesmos campos dos outros eventos. > [!NOTE] > > Repare nos exemplos que `spread` e `net` podem mudar entre `charge.pending` e `charge.paid` (de `0` e `96.5` para `1` e `95.5`). Grave os valores financeiros a partir do `charge.paid` ou da consulta à API depois do pagamento. ## Recusas | Situação | O que você recebe | | - | - | | Recusa ou falha na criação (`POST /v1/charges` ou checkout do link devolvem `refused` ou `failed`) | A resposta HTTP e, de forma complementar, `charge.refused` ou `charge.failed` nos endpoints e no `postbackUrl` | | Recusa ou falha ao final do 3DS gerenciado | `charge.refused` ou `charge.failed` nos endpoints e no `postbackUrl`, mais o `charge.updated` no `postbackUrl` | | Recusa ou falha informada depois pelo adquirente (cobrança em `in_analysis` negada, Pix cancelado ou expirado) | Só o `charge.updated` no `postbackUrl`. Os endpoints não recebem nada | | Cobrança recorrente de assinatura recusada | `subscription.payment_failed`. Não há `charge.refused` nem `charge.failed` | Conforme o adquirente, o status final de uma recusa assíncrona pode ser `failed` em vez de `refused`. No adquirente principal de cartão, a recusa assíncrona, o cancelamento e a expiração terminam em `failed`. Trate os dois valores como "não pago". ## Bloqueio Quando a cobrança é bloqueada, por exemplo por um MED (Mecanismo Especial de Devolução, do Pix) ou por um chargeback em análise, a Finvia envia `charge.blocked` aos endpoints e ao `postbackUrl`. Quem tem `postbackUrl` recebe também o `charge.updated`. * O status continua `paid`. O bloqueio é uma marcação: `is_blocked: true`, com `blocked_at` e `blocked_reason` (no `charge.updated`, `isBlocked`, `blockedAt` e `blockedReason`). * `blocked_reason` é um texto livre preenchido pela Finvia e pode vir vazio. Não decida o fluxo por ele. * A liberação do bloqueio **não gera evento**. Para saber se uma cobrança continua bloqueada, consulte `GET /v1/charges/{id}` e leia `isBlocked`. O `blockedAt` continua preenchido depois da liberação, então não o use para esse fim. * `GET /v1/charges?status=blocked` lista as cobranças bloqueadas. O fluxo completo, com os desfechos, está em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ## Pré-chargeback Um alerta de pré-chargeback chega quando o portador contestou a compra junto ao banco emissor **antes** de o chargeback ser formalizado (programas como Ethoca e Verifi). A cobrança passa para o status `pre_chargeback`, e a Finvia envia: * `charge.pre_chargeback`, no envelope padrão, aos endpoints e ao `postbackUrl`; * `charge.updated` ao `postbackUrl`, com `chargebackAlertRefunded` e `chargebackAlertReason`; * `charge.refunded`, com `chargeback_alert_refunded: true`, quando o valor é estornado como parte do tratamento do alerta. | Campo no `charge.updated` | Tipo | Descrição | | - | - | - | | `chargebackAlertRefunded` | boolean \| null | `true`: o valor **já foi estornado** ao portador como parte do tratamento do alerta. `false`: disputa aberta **sem** estorno | | `chargebackAlertReason` | string \| null | Motivo ou referência informada no alerta (ex.: `"Chargeback - NSU 123456789"`) | Ao registrar o alerta, a Finvia decide se devolve ou não o valor (por padrão, devolve): * **Com estorno** (o caso padrão): o valor é devolvido imediatamente ao portador para evitar que o alerta vire um chargeback formal, com as taxas e penalidades que ele traz. O pedido deve ser tratado como **estornado**. * **Sem estorno**: decisão operacional de contestar e não devolver (por exemplo, mercadoria já entregue com prova de entrega). A disputa segue aberta e o pedido **não** deve ser marcado como estornado. ```json theme={null} { "event": "charge.updated", "data": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "pre_chargeback", "chargebackAlertRefunded": true, "chargebackAlertReason": "Chargeback - NSU 123456789", "amount": 100, "currency": "BRL", "merchantId": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "postbackUrl": "https://meusite.com.br/webhooks/finvia", "isTest": false } } ``` | Recebido | O que fazer no pedido | | - | - | | `charge.refunded` com `chargeback_alert_refunded: true`, ou `charge.updated` com `chargebackAlertRefunded: true` | Marcar como **estornado** (o valor já voltou ao portador) | | `charge.pre_chargeback` sem `charge.refunded`, ou `charge.updated` com `chargebackAlertRefunded: false` | Marcar como **em disputa**, sem estorno | > [!NOTE] > > **Para o negócio:** num pré-chargeback com estorno, o dinheiro já saiu. Se o produto ainda não foi enviado, segure o envio. Se já foi, acione o seu processo de recuperação com o cliente. No caso sem estorno, prepare a documentação de entrega, porque a disputa continua. ## Chargeback formalizado Não existe um evento dedicado ao chargeback formalizado no envelope padrão. Quando o adquirente informa a disputa, a cobrança passa para `chargeback` e a Finvia avisa assim: | Situação | O que você recebe | | - | - | | Sempre que a cobrança vira `chargeback` | `charge.updated` com `status: "chargeback"`, no `postbackUrl` | | A reversão devolve o valor do seu saldo (a cobrança não tinha sido estornada no pré-chargeback) | Também `charge.refunded`, no envelope padrão, aos endpoints e ao `postbackUrl`. O `status` dentro desse payload pode vir `refunded` ou `chargeback` | | A cobrança já tinha sido estornada no alerta de pré-chargeback | Só o `charge.updated` no `postbackUrl`. Os endpoints não recebem nada | A transição automática para `chargeback` acontece nos adquirentes de cartão que enviam esse aviso. Em qualquer caso, confirme o estado com `GET /v1/charges/{id}` antes de registrar a perda. O desenho abaixo resume os eventos que podem chegar depois que a cobrança foi paga. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart LR PAID(["Cobrança paid"]):::ok EST["Estorno concluído
refunded"]:::neutro BLQ["Bloqueio: MED ou
chargeback em análise
status continua paid"]:::alerta PRE["Alerta de pré-chargeback
pre_chargeback"]:::alerta CB["Adquirente informa
a disputa
chargeback"]:::erro E1[["charge.refunded"]]:::evento E2[["charge.blocked
+ charge.updated"]]:::evento LIB["Liberação do bloqueio
nenhum evento: consulte
isBlocked na API"]:::neutro E3[["charge.pre_chargeback
+ charge.updated"]]:::evento Q1{"Valor estornado
no alerta?"}:::decisao E4[["charge.refunded
chargeback_alert_
refunded: true"]]:::evento E5[["charge.updated
status chargeback
só na postbackUrl"]]:::evento Q2{"Já estornado no
pré-chargeback?"}:::decisao E6[["charge.refunded
quando o valor é
revertido do saldo"]]:::evento FIM["Endpoints não
recebem nada"]:::neutro PAID --> EST --> E1 PAID --> BLQ --> E2 BLQ -.-> LIB PAID --> PRE --> E3 PRE --> Q1 Q1 -->|"sim"| E4 PAID --> CB --> E5 CB --> Q2 Q2 -->|"não"| E6 Q2 -->|"sim"| FIM classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Onde aparece `+ charge.updated`, esse evento chega só à `postbackUrl`. ## Postback legado O `charge.updated` é entregue **exclusivamente** ao `postbackUrl` informado na criação da cobrança, nunca aos endpoints, e tem envelope e convenção de nomes próprios. Ele é enviado quando: * o adquirente informa uma mudança de status pelo webhook dele: pagamento, recusa ou falha assíncrona, estorno, chargeback; * o 3DS gerenciado termina em recusa ou falha; * a cobrança é bloqueada; * a cobrança recebe um alerta de pré-chargeback. Por isso, um Pix pago gera `charge.paid` e também `charge.updated` no `postbackUrl`. ### Envelope do charge.updated (camelCase) O envelope **não** tem `id` nem `livemode`. O objeto `data` é a cobrança convertida para **camelCase** em todos os níveis, inclusive as chaves de `metadata`: ```json theme={null} { "event": "charge.updated", "data": { "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE", "status": "failed", "reason": "card_declined", "pspRefId": "card_ref_def456", "amount": 100, "currency": "BRL", "spread": 0, "net": 0, "isBlocked": false, "customer": { "id": "cu_abc123", "name": "Joao Silva", "email": "joao@email.com", "document": { "id": "52998224725", "type": "cpf" }, "phone": null }, "paymentMethod": { "type": "credit_card", "installments": 1, "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2030", "firstSix": "411111", "lastFour": "1111" }, "merchantId": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "paymentDetails": null, "shippingAddress": null, "trackingInfo": null, "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia", "paidAt": null, "isTest": false, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:31:00.000Z", "deletedAt": null } } ``` | Envelope padrão (snake\_case) | `charge.updated` (camelCase) | | - | - | | `psp_ref_id` | `pspRefId` | | `payment_method` | `paymentMethod` (chaves internas iguais: `firstSix`, `lastFour`, `holderName`) | | `merchant_id` | `merchantId` | | `payment_details` | `paymentDetails` | | `shipping_address` | `shippingAddress` | | `tracking_info` | `trackingInfo` | | `postback_url` | `postbackUrl` | | `paid_at` | `paidAt` | | `is_test` | `isTest` | | `is_blocked`, `blocked_at`, `blocked_reason` | `isBlocked`, `blockedAt`, `blockedReason` | | `metadata` com as chaves como foram enviadas | `metadata` com as chaves convertidas para camelCase (veja [Metadata](/guias/cobrancas/visao-geral#metadata)) | | `created_at`, `updated_at`, `deleted_at` | `createdAt`, `updatedAt`, `deletedAt` | | (não vem) | `reason`, o motivo do status | O `charge.updated` traz mais campos que o envelope padrão. Use só os documentados nesta página. Em cobranças Pix, `paymentDetails` traz os mesmos campos descritos em [Objeto payment\_details (Pix)](#objeto-payment_details-pix). > [!TIP] > > **Para o desenvolvedor:** o `charge.updated` não tem `id` de evento. Use a chave definida na [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos). ## Passo a passo O exemplo trata os dois formatos (envelope padrão e `charge.updated`) na mesma rota. Ele responde primeiro e processa depois. Para descartar eventos repetidos, aplique antes do `switch` a [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos), como no exemplo completo da visão geral. ```javascript Node.js theme={null} // webhook-cobranca.mjs (Node.js 18+, ESM) import express from 'express'; const API_URL = 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); async function getCharge(id) { const res = await fetch(`${API_URL}/v1/charges/${id}`, { headers: { Authorization: `Basic ${credentials}` }, }); return res.json(); } // Troque estas funções pelas regras do seu sistema async function releaseOrder(chargeId, info) { console.log('liberar', chargeId, info); } async function markNotPaid(chargeId, status) { console.log('não pago', chargeId, status); } async function markRefunded(chargeId, reason) { console.log('estornado', chargeId, reason); } async function markDisputed(chargeId, reason) { console.log('em disputa', chargeId, reason); } async function markChargeback(chargeId) { console.log('chargeback', chargeId); } const app = express(); app.use(express.json()); app.post('/webhooks/finvia', async (req, res) => { const { event, data, livemode } = req.body; res.status(200).send('OK'); // Eventos de teste chegam nos mesmos endpoints: em produção, descarte-os const isTestEvent = livemode === false || data?.isTest === true; if (process.env.NODE_ENV === 'production' && isTestEvent) return; switch (event) { case 'charge.created': case 'charge.pending': // Pedido aguardando pagamento break; case 'charge.paid': { // Confirmar na API antes de liberar const charge = await getCharge(data.id); // GET /v1/charges/{id} if (charge.status === 'paid') { await releaseOrder(data.id, { paidAt: data.paid_at, net: data.net }); } break; } case 'charge.refused': case 'charge.failed': await markNotPaid(data.id, data.status); break; case 'charge.refunded': await markRefunded(data.id); break; case 'charge.pre_chargeback': // Se houver estorno no alerta, chega também um charge.refunded await markDisputed(data.id); break; case 'charge.blocked': await markDisputed(data.id, data.blocked_reason); break; case 'charge.updated': // Canal legado, entregue só ao postbackUrl, campos em camelCase if (data.status === 'chargeback') { await markChargeback(data.id); } else if (data.status === 'failed' || data.status === 'refused') { await markNotPaid(data.id, data.status); // recusa assíncrona } else if (data.status === 'pre_chargeback' && data.chargebackAlertRefunded) { await markRefunded(data.id, data.chargebackAlertReason); } break; default: console.log(`Evento não tratado: ${event}`); } }); app.listen(3000); ``` > [!TIP] > > **Para o desenvolvedor:** cobranças de assinatura pagas também disparam `charge.created` e `charge.paid`. O `metadata` dessas cobranças traz `subscription_id` e `billing_cycle`, o que permite saber que o pagamento é de uma assinatura. Veja [Webhooks de assinatura](/guias/webhooks/assinatura). ### Fluxo típico de um Pix O desenho abaixo mostra o fluxo típico de um Pix, com os webhooks de cada etapa. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant L as Seu servidor participant W as Seu receptor de webhooks end box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(244,240,255) Fora da Finvia participant B as Banco do comprador end L->>F: POST /v1/charges (type pix) F-->>L: id · status pending · QR Code L-->>C: Mostra o QR Code F-)W: charge.created e charge.pending C->>B: Paga o Pix no app do banco B->>F: Confirma o pagamento F-)W: charge.paid opt Cobrança com postbackUrl F-)W: charge.updated na postbackUrl end W->>F: GET /v1/charges/{id} F-->>W: status paid W-->>C: Libera o acesso ou o pedido ``` **1. Sua aplicação cria a cobrança** `POST /v1/charges` com `paymentMethod.type` `pix`. **2. A resposta traz o QR Code** A resposta síncrona traz o `id`, `status` `pending` e o QR Code. Mostre-o ao cliente. **3. Webhooks de criação e espera** Chegam `charge.created` e `charge.pending`. **4. O cliente paga** O cliente paga o Pix no aplicativo do banco. **5. Webhook de pagamento** Chega `charge.paid` e, se a cobrança tem `postbackUrl`, também o `charge.updated`. Sua aplicação confirma em `GET /v1/charges/{id}` e libera o acesso. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `charge.updated` nunca chega | Cobrança criada sem `postbackUrl`, ou esperado nos endpoints | Informe `postbackUrl` na criação da cobrança | | Campos `undefined` no `charge.updated` | Parser lendo snake\_case (`paid_at`) em um payload camelCase (`paidAt`) | Trate o `charge.updated` com o mapeamento de camelCase | | `metadata.order_id` vazio no postback | No `charge.updated`, chaves enviadas em snake\_case chegam em camelCase | Leia `metadata.orderId` nesse evento ou envie as chaves em camelCase. Veja [Metadata](/guias/cobrancas/visao-geral#metadata) | | Cobrança em análise negada sem aviso nos endpoints | Recusas assíncronas só geram `charge.updated` | Use `postbackUrl` ou consulte `GET /v1/charges/{id}` | | Pedido continua "em disputa" depois da liberação do bloqueio | A liberação não gera evento | Consulte `isBlocked` em `GET /v1/charges/{id}` | | QR Code em branco | `qrCodeBase64` veio `null` | Gere a imagem a partir de `copyPaste` | | Pedido de pré-chargeback marcado errado | Status lido sem olhar se houve estorno | Use `charge.refunded` ou `chargebackAlertRefunded` para decidir entre estornado e em disputa | ## Perguntas frequentes > [accordion] Qual evento devo usar para liberar o pedido? > > `charge.paid`, sempre confirmado por `GET /v1/charges/{id}`. Os webhooks não têm assinatura HMAC, por isso a confirmação na API é necessária antes de liberar. > [accordion] Por que existem dois formatos de payload? > > O envelope padrão atende os eventos entregues aos endpoints e ao `postbackUrl`. O `charge.updated` é um canal legado, entregue só ao `postbackUrl`, com a cobrança em camelCase. Os dois formatos são mantidos por compatibilidade com integrações em produção. > [accordion] Recebo webhook de recusa de cartão? > > Sim, quando a recusa acontece na criação ou ao final do 3DS gerenciado: chega `charge.refused` ou `charge.failed`. A resposta de `POST /v1/charges` continua sendo a fonte principal, com o motivo em `reason`. Recusas informadas depois pelo adquirente chegam só pelo `charge.updated`. > [accordion] Como recebo aviso de chargeback e MED? > > O bloqueio chega como `charge.blocked`, nos endpoints e no `postbackUrl`. O chargeback formalizado chega como `charge.updated` com `status: "chargeback"` no `postbackUrl` e, quando o valor sai do saldo, também como `charge.refunded`. A liberação do bloqueio não gera aviso. O fluxo completo está em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). > [accordion] Sou conta master. Recebo os eventos das cobranças das subcontas? > > Sim, se o seu endpoint tiver a opção de incluir subcontas (`include_submerchants: true`). O `merchant_id` do payload indica a subconta. Veja [Quem recebe cada evento](/guias/webhooks/visao-geral#quem-recebe-cada-evento). ## Como testar | Código | Cenário | O que comprovar | | - | - | - | | CHG-01 | Cartão aprovado à vista | Webhook `charge.paid` recebido | | CHG-03 | Cartão recusado | Recusa na resposta síncrona e webhook `charge.refused` (ou `charge.failed`) | | CHG-04 | Pix gerado | Webhook `charge.pending` | | CHG-05 | Pix pago no sandbox | Webhook `charge.paid` para o mesmo `id` | | CHG-07 | Estorno total | Webhook `charge.refunded` | | CHG-08 | Recebimento de webhook | Seu endpoint responde `2xx` em poucos segundos | | CHG-09 | Simulação de evento no sandbox | Evento simulado recebido nos endpoints e no `postbackUrl` | Para testar o tratamento de outros status, use [`POST /v1/charges/{id}/resend-webhook`](/referencia/cobrancas/reenviar-webhook-teste) com uma cobrança de teste. A rota aceita `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis` e `authentication_required`, gera um evento novo e não muda a cobrança. Bloqueio, pré-chargeback e chargeback não podem ser simulados por ela. ## Veja também > [card] [Webhooks: visão geral](/guias/webhooks/visao-geral) > > Destinos, formatos, entrega e deduplicação. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > O fluxo de disputa e o campo isBlocked. > [card] [Status de cobrança](/anexos/status-de-cobranca) > > Todos os status e o que fazer em cada um. > [card] [Reenviar webhook de teste](/referencia/cobrancas/reenviar-webhook-teste) > > Simule eventos no sandbox. # Webhooks de conta Source: https://docs.fastpaybrasil.com/guias/webhooks/conta Aviso de mudança no status de aprovação das subcontas do Connect: pré-aprovada, em correção, ativa, rejeitada ou bloqueada. Toda subconta (SubMerchant) criada no [Connect](/guias/fast-connect/visao-geral) passa por análise antes de poder vender. Este aviso informa ao seu sistema quando o status de aprovação da subconta muda: pré-aprovada, aprovada, devolvida para correção, rejeitada, bloqueada ou desbloqueada. > [!NOTE] > > **Para o negócio:** num marketplace ou numa plataforma que cadastra vendedores, este aviso permite liberar o vendedor para vender no momento em que a conta é aprovada e avisá-lo assim que a análise pedir uma correção. Sem ele, o seu time precisa conferir o painel para saber em que pé está cada cadastro. ## Quando usar | Situação | Status que chega | | - | - | | Mostrar ao vendedor que os documentos obrigatórios foram conferidos | `pre_approved` | | Liberar a venda e as chaves de API da subconta | `active` | | Pedir ao vendedor que corrija dados ou documentos | `correcting` (com `rejectionReason`) | | Encerrar o cadastro e comunicar a recusa | `rejected` (com `rejectionReason`) | | Suspender a operação do vendedor | `blocked` | | Retomar a operação depois de um bloqueio | `active` | ## Como funciona **1. Subconta criada com a URL de aviso** A conta master cria a subconta em `POST /v1/submerchants` e informa `postbackUrl`. A subconta nasce com status `pending`, e essa criação **não** gera aviso. **2. Análise da Finvia** A equipe da Finvia analisa os dados e os documentos enviados. **3. Mudança de status** A cada mudança para `pre_approved`, `correcting`, `active`, `rejected` ou `blocked`, a Finvia envia um `POST` com o novo status para a URL de aviso de status da subconta. **4. Seu sistema reage** Libera a subconta, pede correção ao vendedor ou encerra o cadastro, conforme o status. ## Canal e configuração O aviso de status de conta tem um canal próprio: | Ponto | Como funciona | | - | - | | Onde se informa a URL | No campo `postbackUrl` de [`POST /v1/submerchants`](/referencia/fast-connect/criar-subconta). Nesse cadastro, `postbackUrl` é gravado nas configurações da subconta como `merchant_status_postback_url` e recebe os avisos de mudança de status. Ele não recebe eventos de cobrança | | Sem `postbackUrl` no cadastro | A subconta herda a `merchant_status_postback_url` da conta master, se a master tiver uma, porque as configurações da master são copiadas na criação da subconta | | Alterar a URL depois | Não há rota pública para isso. Peça a troca ao suporte da Finvia | | O que não recebe este aviso | Os endpoints de webhook (da subconta ou da master) e o `postbackUrl` das cobranças | > [!TIP] > > **Para o desenvolvedor:** informe `postbackUrl` na criação de cada subconta, mesmo que a master já tenha uma URL configurada. Assim o destino fica explícito no seu código e você não depende da cópia das configurações da master. ## Status possíveis e status que geram aviso A subconta tem sete status possíveis no ciclo de vida, mas **só cinco geram aviso**. | Status | Significado | Gera aviso? | | - | - | - | | `pending` | Cadastro recebido, em análise. Também é o status depois que o vendedor reenvia uma correção | Não | | `pre_approved` | Documentos obrigatórios conferidos. A subconta está sendo credenciada nas adquirentes e aguarda a aprovação final | Sim | | `correcting` | A Finvia pediu correção de dados ou documentos. O motivo vem em `rejectionReason` | Sim | | `active` | Aprovada e apta a transacionar. Também é o status depois de um desbloqueio | Sim, na aprovação e no desbloqueio | | `rejected` | Reprovada | Sim | | `blocked` | Bloqueada | Sim | | `inactive` | Inativada | Não | > [!WARNING] > > Não espere aviso para `pending` nem para `inactive`. Para saber desses status, consulte a subconta em [`GET /v1/submerchants/{merchantId}`](/referencia/fast-connect/consultar-subconta). Em especial, depois que o vendedor reenvia os dados corrigidos, a conta volta para análise sem aviso. O próximo aviso chega só quando a análise avançar. ## Ciclo de vida da aprovação O fluxo comum é **`pending` → `pre_approved` → `active`**. O desenho abaixo mostra todas as transições e quais geram aviso, com o caminho comum em seta grossa. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB NEW(["POST /v1/submerchants
com postbackUrl"]):::lojista PEN["pending
em análise"]:::alerta PRE["pre_approved
documentos conferidos"]:::alerta COR["correcting
correção pedida
com rejectionReason"]:::alerta ACT["active
apta a transacionar"]:::ok REJ["rejected
reprovada"]:::erro BLK["blocked
bloqueada"]:::erro INA["inactive
inativada"]:::neutro NEW -.->|"sem aviso"| PEN PEN ==>|"aviso"| PRE PEN -->|"aviso"| COR PRE -->|"aviso"| COR COR -.->|"vendedor reenvia
sem aviso"| PEN PRE ==>|"aprovação final
aviso"| ACT PEN -->|"aviso"| REJ PRE -->|"aviso"| REJ COR -->|"aviso"| REJ ACT -->|"bloqueio
aviso"| BLK BLK -->|"desbloqueio
aviso"| ACT ACT -.->|"sem aviso"| INA classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` As setas pontilhadas são mudanças sem aviso: acompanhe esses casos por `GET /v1/submerchants/{merchantId}`. | De | Para | Motivo | Gera aviso? | | - | - | - | - | | (criação) | `pending` | Conta criada | Não | | `pending` | `pre_approved` | Documentos obrigatórios conferidos | Sim | | `pending` ou `pre_approved` | `correcting` | Dados ou documentos precisam de correção | Sim | | `correcting` | `pending` | Vendedor reenvia os dados | Não | | `pre_approved` | `active` | Aprovação final, que só parte de `pre_approved` | Sim | | `pending`, `pre_approved` ou `correcting` | `rejected` | Reprovação | Sim | | `active` | `blocked` | Bloqueio | Sim | | `blocked` | `active` | Desbloqueio | Sim | | `active` | `inactive` | Inativação | Não | ## Correção de dados (status `correcting`) Quando a análise pede correções, a subconta recebe o status `correcting` e o motivo vem no campo `rejectionReason`. A correção é feita no painel da Finvia, na gestão de subcontas, na área de correções pendentes. Depois do reenvio, a conta volta para análise (`pending`), sem aviso. > [!NOTE] > > **Para o negócio:** se a sua plataforma cadastra vendedores por API, combine internamente quem vai fazer a correção no painel quando chegar um `correcting`. Pode ser o seu time de operações (com os dados enviados pelo vendedor) ou o próprio vendedor, se ele tiver acesso ao painel. Mostre ao vendedor o texto de `rejectionReason`, que descreve o que precisa ser corrigido. ## Payload O aviso é enviado por `POST`, sem envelope: o corpo é o próprio objeto de notificação, em camelCase. Não há nome de evento, id de evento nem marcação de teste. > [tab] Aprovação > > ```json theme={null} > { > "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", > "status": "active", > "date": "2024-01-15T14:30:00.000Z" > } > ``` > [tab] Rejeição ou correção > > O campo `rejectionReason` vem **somente** quando o status é `rejected` ou `correcting`. > > ```json theme={null} > { > "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", > "status": "correcting", > "date": "2024-01-16T09:15:00.000Z", > "rejectionReason": "Documento de identidade ilegível. Reenvie o RG ou CNH com qualidade adequada." > } > ``` ### Campos | Campo | Tipo | Quando vem | Descrição | | - | - | - | - | | `merchantId` | string | Sempre | ID da subconta cujo status mudou | | `status` | string | Sempre | Novo status (`pre_approved`, `correcting`, `active`, `rejected` ou `blocked`) | | `date` | string (ISO 8601) | Sempre | Data de referência do status. Veja a tabela abaixo | | `rejectionReason` | string | Só em `rejected` ou `correcting` | Motivo da recusa ou descrição das correções necessárias | `date` é a data de referência do status, e o valor depende de qual status chegou: | Status | O que `date` traz | | - | - | | `active` | A data de aprovação. No desbloqueio, continua sendo a data original de aprovação | | `pre_approved` | A data da última atualização da conta | | `rejected` e `correcting` | A data da recusa | | `blocked` | A data do bloqueio | ## Regras de negócio | Regra | Detalhe | | - | - | | Confirmação de recebimento | Só uma resposta `2xx` conta como entregue | | Entrega | Veja [Entrega e retentativas](/guias/webhooks/visao-geral#entrega-e-retentativas) | | Entrega repetida | O mesmo aviso pode chegar mais de uma vez | | Deduplicação | Compare o status recebido com o último status gravado para a subconta, conforme a [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos). Não use `date` como parte de uma chave única: no desbloqueio, o aviso `active` repete a data da aprovação | | Teste e produção | O aviso não tem marcação de teste | | Correção | Só pelo painel | ## Passo a passo O desenho abaixo mostra como tratar cada aviso de status no seu sistema. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB REQ(["POST na URL de aviso
merchantId · status · date"]):::neutro R2["Responda 2xx"]:::lojista IG{"Status igual ao
último gravado?"}:::decisao IGN["Ignore: aviso repetido"]:::neutro GRV["Grave o novo status"]:::lojista GET["Confirme na API
GET /v1/submerchants/
{merchantId}"]:::lojista ST{"Qual status?"}:::decisao A1["pre_approved
mostre que a análise
está na etapa final"]:::alerta A2["active
libere a venda e busque
as chaves da subconta"]:::ok A3["correcting
avise vendedor e equipe
a correção é no painel"]:::alerta A4["rejected
encerre o cadastro e
mostre o rejectionReason"]:::erro A5["blocked
suspenda a operação
do vendedor"]:::erro REQ --> R2 --> IG IG -->|"sim"| IGN IG -->|"não"| GRV --> GET --> ST ST --> A1 ST --> A2 ST --> A3 ST --> A4 ST --> A5 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` ```javascript Node.js theme={null} // webhook-conta.mjs (Node.js 18+, ESM) import express from 'express'; // Troque pelo cadastro de vendedores do seu sistema const sellers = { getStatus: async (id) => null, setStatus: async (id, status) => console.log(id, status), enable: async (id) => console.log('liberar', id), requestCorrection: async (id, reason) => console.log('corrigir', id, reason), reject: async (id, reason) => console.log('recusar', id, reason), suspend: async (id) => console.log('suspender', id), }; const app = express(); app.use(express.json()); app.post('/webhooks/finvia/conta', async (req, res) => { const { merchantId, status, rejectionReason } = req.body; res.status(200).send('OK'); // Deduplicação: ignore se o status já é o mesmo que você tem gravado const atual = await sellers.getStatus(merchantId); if (atual === status) return; await sellers.setStatus(merchantId, status); switch (status) { case 'pre_approved': // Mostre ao vendedor que a análise está na etapa final break; case 'active': // Aprovação ou desbloqueio: liberar a venda e buscar as chaves da subconta await sellers.enable(merchantId); break; case 'correcting': // Correção só pelo painel: avise o vendedor e o time de operações await sellers.requestCorrection(merchantId, rejectionReason); break; case 'rejected': await sellers.reject(merchantId, rejectionReason); break; case 'blocked': await sellers.suspend(merchantId); break; default: console.log(`Status para ${merchantId}: ${status}`); } }); app.listen(3000); ``` > [!TIP] > > **Para o desenvolvedor:** como o aviso não tem assinatura, confirme o status em [`GET /v1/submerchants/{merchantId}`](/referencia/fast-connect/consultar-subconta) antes de liberar a subconta. Quando chegar `active`, as chaves de API da subconta podem ser consultadas em [Chaves de API da subconta](/referencia/fast-connect/chaves-de-api). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | O aviso não chega nos endpoints de webhook | Este aviso tem canal próprio, a URL de aviso de status da subconta | Informe `postbackUrl` na criação da subconta | | O aviso vai para uma URL antiga | A subconta herdou a URL da master ou foi criada com outra URL | Peça a troca ao suporte da Finvia | | Parser falha procurando `event` ou `data` | O payload não tem envelope | Leia `merchantId`, `status`, `date` e `rejectionReason` direto do corpo | | Desbloqueio ignorado pelo seu sistema | Deduplicação feita por `merchantId` + `status` + `date`, e o `active` do desbloqueio repete a data da aprovação | Compare com o último status gravado | | Entrega contada como falha | O endpoint respondeu `3xx`, `4xx` ou `5xx` | Responda `2xx` | | Nunca chega aviso de `pending` | `pending` não gera aviso | Consulte a subconta pela API | ## Perguntas frequentes > [accordion] Quanto tempo leva para a subconta ser aprovada? > > A documentação não define prazo. Acompanhe pelo aviso de status e, se precisar de previsão, consulte o seu contato na Finvia. > [accordion] A subconta voltou para pending depois da correção e não recebi aviso. Está certo? > > Sim. A volta para `pending` após o reenvio dos dados não gera aviso. O próximo aviso chega quando a análise mudar o status para `pre_approved`, `correcting`, `active` ou `rejected`. > [accordion] Esqueci de informar o postbackUrl na criação. E agora? > > Se a conta master tiver uma URL de aviso de status configurada, a subconta herdou essa URL. Para definir ou trocar a URL, peça ao suporte da Finvia. Enquanto isso, acompanhe o status por `GET /v1/submerchants/{merchantId}`. > [accordion] O bloqueio é permanente? > > Não necessariamente. A conta pode voltar para `active` com o desbloqueio, o que gera um novo aviso `active`. ## Como testar | Código | Cenário | O que comprovar | | - | - | - | | FC-01 | Criar subconta com `postbackUrl` | Subconta criada com status `pending` | | FC-03 | Consultar a subconta até a aprovação | Status evolui até `active` | | FC-08 | Receber o aviso de mudança de status | Aviso recebido e respondido com `2xx` | ## Veja também > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Cadastro e análise das subcontas. > [card] [Criar subconta](/referencia/fast-connect/criar-subconta) > > Contrato completo, incluindo o postbackUrl. > [card] [Webhooks de saque](/guias/webhooks/saque) > > Avisos de saque das subcontas. > [card] [Webhooks: visão geral](/guias/webhooks/visao-geral) > > Destinos, formatos, entrega e deduplicação. # Webhooks de saque Source: https://docs.fastpaybrasil.com/guias/webhooks/saque Avisos de aprovação e rejeição dos saques das subcontas do Connect: quem recebe, formato e como tratar os valores. Quando uma subconta do [Connect](/guias/fast-connect/visao-geral) tem um saque (payout) solicitado, a solicitação fica pendente até ser aprovada ou rejeitada. Os webhooks de saque avisam o resultado: `payout.approved` quando o saque foi aprovado e enviado para pagamento, e `payout.rejected` quando a solicitação foi recusada, com o motivo. > [!NOTE] > > **Para o negócio:** em um marketplace, o vendedor quer saber quando o saque sai. Com estes eventos, a sua plataforma mostra ao vendedor o status do saque e o valor líquido, sem que ninguém precise conferir o painel. Se o saque for rejeitado, o motivo chega junto, e o seu time de suporte pode orientar o vendedor. ## Quando usar | Situação | Evento | | - | - | | Mostrar ao vendedor que o saque foi aprovado e enviado para pagamento, com valor líquido e taxa | `payout.approved` | | Avisar o vendedor que o saque não foi feito e por quê | `payout.rejected` | | Saque da própria conta (conta master ou conta sem Connect) | Não há webhook. Acompanhe pela [listagem de saques](/referencia/saques/listar) | ## Como funciona O desenho abaixo mostra o caminho de um saque de subconta, do pedido ao webhook. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(243,245,248) Sua aplicação participant P as Sua plataforma participant W as Seu receptor de webhooks end box rgb(234,243,255) Finvia participant F as Finvia API participant O as Operação Finvia end box rgb(244,240,255) Fora da Finvia participant X as Provedor de pagamento end P->>F: POST /v1/submerchants/{merchantId}/payout-requests · chave da master F-->>P: 201 · id do saque Note over F,O: Saque nasce pending e o valor bruto sai do saldo disponível da subconta. A subconta também pode pedir com a chave dela, em POST /v1/payout-requests F->>O: Solicitação aguarda decisão alt Aprovado O->>X: Pix do valor líquido para a chave CNPJ da subconta F-)W: payout.approved · amount · payoutFee · netAmount else Rejeitado Note over F,O: O valor reservado volta ao saldo disponível F-)W: payout.rejected · rejectionReason end Note over W,F: Vai aos endpoints da subconta e aos da master com include_submerchants W->>W: Deduplica por id + event e converte os valores de texto W->>P: Atualiza o saque e avisa o vendedor ``` **1. O saque da subconta é solicitado** A conta master solicita em `POST /v1/submerchants/{merchantId}/payout-requests`, ou a própria subconta solicita com a chave dela. Em qualquer caso, a solicitação nasce com status `pending` e o valor bruto sai do saldo disponível. **2. A Finvia decide** A solicitação é aprovada ou rejeitada pela operação da Finvia. Na aprovação, o Pix do valor líquido é enviado ao provedor de pagamento. Na rejeição, o valor reservado volta ao saldo disponível. **3. A Finvia escolhe os destinos** O aviso vai para os endpoints de webhook cadastrados na subconta e para os endpoints da conta master cadastrados com a opção de incluir subcontas (`include_submerchants: true`). Em cada endpoint, vale o filtro de eventos (`enabled_events`); lista vazia recebe todos. **4. O webhook é enviado** O aviso é enviado depois que os dados foram gravados, então uma consulta feita ao receber o webhook já mostra o resultado. Uma falha de entrega não interrompe a aprovação nem a rejeição. ## Eventos disponíveis | Evento | Quando é enviado | | - | - | | `payout.approved` | A solicitação de saque é aprovada e o pagamento é enviado | | `payout.rejected` | A solicitação de saque é rejeitada | Não há evento de criação do saque. Para saber que um saque foi solicitado, use a resposta da criação ou a [listagem de saques](/referencia/saques/listar). ## Regras de negócio | Regra | Detalhe | | - | - | | Quais saques geram webhook | Só os saques de subconta, qualquer que seja a rota usada para criar. O saque da própria conta não gera webhook | | Quem recebe | Endpoints da subconta e endpoints da conta master com `include_submerchants: true`. Veja [Quem recebe cada evento](/guias/webhooks/visao-geral#quem-recebe-cada-evento) | | Destino do dinheiro | Pix para a chave CNPJ da subconta (o mesmo CNPJ do cadastro). Detalhes em [Saques do Connect](/guias/fast-connect/saques) | | Moeda | `BRL` | | Valores | `amount`, `payoutFee` e `netAmount` chegam como **texto decimal com 8 casas**, em reais (ex.: `"100.00000000"`). Converta antes de calcular ou exibir | | Assinatura | As mensagens não têm cabeçalho de assinatura. Confirme o status pela listagem de saques antes de agir | | Teste | Os eventos de saque não têm marcação de teste. Saques não existem no Modo Teste: com `sk_test_`, a criação responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | | Entrega | Veja [Entrega e retentativas](/guias/webhooks/visao-geral#entrega-e-retentativas) | > [!WARNING] > > Mantenha uma rotina que consulte a [listagem de saques](/referencia/saques/listar) para conciliar os saques ainda marcados como pendentes no seu sistema. Filtre por `merchantId` para ver uma subconta só e use `status=pending` para achar os que aguardam decisão. ## Status do saque | Valor | Significado | | - | - | | `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda a decisão | | `approved` | Aprovado e enviado para pagamento | | `rejected` | Rejeitado. O valor reservado volta ao saldo disponível e o motivo fica em `rejectionReason` | O webhook só chega com `approved` ou `rejected`. `approved` significa que o Pix do valor líquido foi enviado ao provedor no momento da aprovação. Não trate esse status como confirmação de crédito na conta bancária do vendedor. ## Envelope (camelCase) O envelope do saque é mais simples que o de cobrança: o `id` da raiz é o **id da solicitação de saque**, igual a `data.id`, e se repete nos eventos do mesmo saque. Não há id de evento próprio, `livemode`, `processedAt` nem `createdAt`. ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "event": "payout.approved", "data": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "amount": "100.00000000", "currency": "BRL", "status": "approved", "payoutFee": "1.00000000", "netAmount": "99.00000000" } } ``` **Em validação (V-16):** há uma mudança em desenvolvimento no webhook de saque: id de evento próprio na raiz, campo `livemode`, registro de entrega e envio também para os saques da conta master. Esta página descreve o formato atual. Escreva o parser aceitando campos adicionais sem erro. ### Campos do objeto `data` | Campo | Tipo | Descrição | | - | - | - | | `id` | string | ID da solicitação de saque | | `merchantId` | string | ID da subconta que fez o saque | | `amount` | string | Valor bruto solicitado, em reais, como texto decimal com 8 casas | | `currency` | string | Código ISO da moeda (`BRL`) | | `status` | string | `approved` ou `rejected` | | `payoutFee` | string | Taxa de saque, em reais, como texto decimal com 8 casas | | `netAmount` | string | Valor líquido depois da taxa (`amount` menos `payoutFee`), em reais, como texto decimal com 8 casas | | `rejectionReason` | string | Motivo da rejeição. **Presente apenas em** `payout.rejected` | ### Valores em texto decimal Os valores chegam como texto: `"100.00000000"` é R\$ 100,00. Converta antes de usar. Em JavaScript, `data.netAmount.toFixed(2)` dá erro, porque `toFixed` não existe em texto. ```javascript theme={null} const netAmount = Number(data.netAmount); // 99 const formatado = new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }).format(netAmount); // "R$ 99,00" ``` Para somar ou guardar valores financeiros, prefira um tipo decimal do seu banco ou uma biblioteca de decimais, partindo do texto recebido. ## Payloads por evento > [tab] payout.approved > > Enviado depois da aprovação da solicitação e do envio do pagamento. > > ```json theme={null} > { > "id": "2vorkDcXyvzifL63YX09S9VqcnI", > "event": "payout.approved", > "data": { > "id": "2vorkDcXyvzifL63YX09S9VqcnI", > "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", > "amount": "100.00000000", > "currency": "BRL", > "status": "approved", > "payoutFee": "1.00000000", > "netAmount": "99.00000000" > } > } > ``` > [tab] payout.rejected > > Enviado quando a solicitação é rejeitada. O motivo vem em `rejectionReason`. > > ```json theme={null} > { > "id": "2vorkDcXyvzifL63YX09S9VqcnI", > "event": "payout.rejected", > "data": { > "id": "2vorkDcXyvzifL63YX09S9VqcnI", > "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", > "amount": "100.00000000", > "currency": "BRL", > "status": "rejected", > "payoutFee": "1.00000000", > "netAmount": "99.00000000", > "rejectionReason": "Documentação incompleta" > } > } > ``` ## Configuração > [tab] Pelo painel > > No [painel da Finvia](https://app.finvia.com.br), selecione a conta e vá em **Configurações** > **Webhooks**. Há dois caminhos: > > * Na conta master, cadastre um endpoint com a opção de incluir subcontas. Ele recebe os saques de todas as subcontas. > * Com a subconta selecionada, cadastre um endpoint só para ela. > > O endpoint cadastrado pelo painel recebe todos os eventos (cobrança, assinatura e saque). > [tab] Pela API > > Use [`POST /v1/webhook-endpoints`](/referencia/webhooks/criar-endpoint). Para receber só os eventos de saque de todas as subcontas, cadastre na master: > > ```bash cURL theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD" \ > -u "$FINVIA_API_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "url": "https://meusite.com.br/webhooks/finvia/saques", > "enabled_events": ["payout.approved", "payout.rejected"], > "include_submerchants": true > }' > ``` > > Para cadastrar o endpoint numa subconta, a master usa a própria chave secreta com `merchantId` igual ao id da subconta. ## Passo a passo ```javascript Node.js theme={null} // webhook-saque.mjs (Node.js 18+, ESM) import express from 'express'; // Exemplo em memória. Em produção, grave as chaves no seu banco. const seen = new Set(); // Troque pelas regras do seu sistema const payouts = { update: async (id, info) => console.log('saque', id, info) }; async function notifySeller(merchantId, text) { console.log(merchantId, text); } const brl = new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }); const app = express(); app.use(express.json()); app.post('/webhooks/finvia/saques', async (req, res) => { const { id, event, data } = req.body; res.status(200).send('OK'); // Deduplicação pelo corpo: id da raiz (id do saque) + event const key = `payout:${id}:${event}`; if (seen.has(key)) return; seen.add(key); switch (event) { case 'payout.approved': // Valores chegam como texto decimal: guarde o texto e converta só para exibir await payouts.update(data.id, { status: 'approved', netAmount: data.netAmount, fee: data.payoutFee, }); await notifySeller(data.merchantId, `Saque de ${brl.format(Number(data.netAmount))} aprovado.`); break; case 'payout.rejected': await payouts.update(data.id, { status: 'rejected', reason: data.rejectionReason }); await notifySeller(data.merchantId, `Saque rejeitado: ${data.rejectionReason}`); break; default: console.log(`Evento não tratado: ${event}`); } }); app.listen(3000); ``` > [!TIP] > > **Para o desenvolvedor:** o `id` da raiz é o id do saque, por isso a chave pelo corpo é `id` + `event`, conforme a [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos). Eventos diferentes do mesmo saque não se confundem. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | A conta master não recebe os avisos de saque | O endpoint da master não tem a opção de incluir subcontas | Ative a opção no endpoint da master ou cadastre um endpoint na subconta | | Nenhum aviso chega | Nenhum endpoint na subconta nem na master com a opção ligada, ou evento fora de `enabled_events` | Revise os endpoints e os eventos habilitados (lista vazia recebe todos) | | `TypeError` ao formatar o valor | Os valores chegam como texto | Converta com `Number()` ou com um tipo decimal antes de calcular | | `rejectionReason` indefinido | Leitura do campo em `payout.approved` | O campo só existe em `payout.rejected` | | Esperando webhook no saque da própria conta | Só saques de subconta geram webhook | Acompanhe pela listagem de saques | ## Perguntas frequentes > [accordion] Sou a conta master. Como acompanho os saques dos meus vendedores? > > Cadastre um endpoint na conta master com a opção de incluir subcontas (`include_submerchants: true`). Ele recebe os eventos de saque de todas as subcontas, e `data.merchantId` indica de qual subconta é o saque. Para conciliar, consulte a [listagem de saques](/referencia/saques/listar). > [accordion] O saque da minha própria conta gera webhook? > > Não. Só os saques de subconta geram webhook. O saque da própria conta é acompanhado pela listagem, que traz os saques do mais recente para o mais antigo. > [accordion] Para onde vai o dinheiro do saque? > > Para a chave Pix do tipo CNPJ igual ao CNPJ cadastrado na subconta. A moeda é `BRL`. > [accordion] Como a taxa de saque aparece? > > Em `payoutFee`, em reais, como texto decimal. O valor que o vendedor recebe é `netAmount`, que é `amount` menos a taxa. O cálculo está em [Saques do Connect](/guias/fast-connect/saques). > [accordion] approved quer dizer que o dinheiro caiu na conta do vendedor? > > Significa que o saque foi aprovado e que o Pix do valor líquido foi enviado para pagamento. Se o vendedor não receber, acione o suporte da Finvia com o id do saque. ## Como testar Saques não existem no Modo Teste, então o webhook de saque só pode ser observado com um saque real de subconta, em produção, de valor baixo. | Código | Cenário | O que comprovar | | - | - | - | | FC-07 | Saque da subconta | Solicitação criada com status `pending` | | PAY-06 | Acompanhar o status pela listagem | Status `pending`, `approved` ou `rejected` visível na listagem de saques | Guarde o registro do webhook `payout.approved` ou `payout.rejected` recebido e a resposta HTTP que o seu endpoint devolveu. ## Veja também > [card] [Saques do Connect](/guias/fast-connect/saques) > > Como a subconta solicita e acompanha saques. > [card] [Listar saques](/referencia/saques/listar) > > Consulta de solicitações com filtros. > [card] [Criar endpoint de webhook](/referencia/webhooks/criar-endpoint) > > Cadastro com include\_submerchants e filtro de eventos. > [card] [Webhooks: visão geral](/guias/webhooks/visao-geral) > > Destinos, formatos, entrega e deduplicação. # Webhooks: visão geral Source: https://docs.fastpaybrasil.com/guias/webhooks/visao-geral Receba no seu sistema os avisos de pagamento, estorno, bloqueio, assinatura, saque e conta, e saiba quem recebe cada evento e em que formato. Um webhook é uma notificação que a Finvia envia ao seu sistema quando algo acontece: um Pix foi pago, um estorno foi concluído, uma assinatura renovou, um saque foi aprovado. Com webhooks, a sua aplicação fica sabendo da mudança logo depois que ela acontece, sem precisar consultar a API repetidamente para descobrir se o status mudou (prática chamada de polling). > [!NOTE] > > **Para o negócio:** é o webhook que permite liberar o pedido, o acesso ao curso ou o envio do produto assim que o pagamento é confirmado. Sem ele, a confirmação depende de alguém conferir o painel ou de uma rotina que consulta a API de tempos em tempos. Ao contratar a integração, garanta que o time técnico trate os eventos que importam para a sua operação: pagamento confirmado, estorno, bloqueio, falha de assinatura e mudança de status de subconta. ## Quando usar | Situação | O que o webhook resolve | | - | - | | Venda por Pix | O cliente paga minutos depois da criação da cobrança. O evento `charge.paid` avisa o momento exato | | Assinatura | A renovação acontece sem ninguém na tela. Os eventos `subscription.*` avisam renovação, falha e cancelamento | | Estorno e disputas | `charge.refunded`, `charge.pre_chargeback` e `charge.blocked` avisam estorno, alerta de pré-chargeback e bloqueio. O postback `charge.updated` avisa o chargeback formalizado | | Marketplace com Connect | Os eventos `payout.*` e o aviso de status de conta informam saques e aprovação das subcontas | Quando **não** depender de webhook: na cobrança de cartão, aprovação e recusa voltam na própria resposta de `POST /v1/charges`. Use a resposta para decidir o que mostrar ao cliente no checkout e o webhook para manter o seu sistema atualizado depois. ## Como funciona **1. Você cadastra um destino** Você cadastra um endpoint de webhook, que é o endereço do seu servidor que recebe os avisos, pelo painel ou pela API. Opcionalmente, cada cobrança pode levar a sua própria URL no campo `postbackUrl`. **2. Um evento acontece** Por exemplo, o cliente paga o QR Code Pix e a cobrança passa para `paid`. **3. A Finvia envia um POST** A Finvia faz uma requisição HTTP `POST` para cada destino que deve receber o evento, com um corpo JSON (`Content-Type: application/json`) que descreve o evento e traz o recurso. **4. Seu servidor confirma o recebimento** O seu endpoint responde com um status `2xx` (de `200` a `299`) em até 10 segundos. Qualquer outro resultado conta como falha de entrega: erro de conexão, tempo esgotado, redirecionamento (`3xx`, que não é seguido), `4xx` ou `5xx`. **5. Sua aplicação processa o evento** Depois de responder, a sua aplicação confere o status na API e executa a regra de negócio: libera o pedido, atualiza o financeiro, envia o e-mail. ## Webhook e postback A Finvia tem dois canais de notificação de cobrança. Eles convivem e podem ser usados juntos. | | Webhook (endpoints) | Postback (`postbackUrl`) | | - | - | - | | Onde se configura | No painel ou em [`POST /v1/webhook-endpoints`](/referencia/webhooks/criar-endpoint), uma vez, para a conta | No corpo de cada `POST /v1/charges` | | Abrangência | Cobranças, assinaturas e saques da conta dona do endpoint | Somente a cobrança em que a URL foi informada | | Filtro de eventos | Pela API, com `enabled_events`. O endpoint cadastrado pelo painel recebe todos os eventos | Não há filtro: recebe todos os eventos de cobrança | | Eventos | Envelope padrão de cobrança, assinatura e saque | Os mesmos eventos de cobrança dos endpoints, mais o `charge.updated` legado | | Uso típico | Integração principal do sistema | Plataformas que precisam de uma URL diferente por pedido ou por cliente, e quem precisa do `charge.updated` | O `postbackUrl` é um canal **assíncrono**. Ele recebe os eventos da cobrança **depois** que ela foi criada e não substitui a resposta da criação. O QR Code e a validade do Pix chegam na resposta síncrona de `POST /v1/charges`. > [!WARNING] > > Se a mesma URL estiver cadastrada como endpoint e também for enviada como `postbackUrl`, ela recebe cada evento de cobrança duas vezes. Use URLs diferentes ou deixe a [deduplicação](#como-descartar-eventos-repetidos) cuidar da repetição. ## Quem recebe cada evento Os eventos de cobrança, de assinatura e de saque são entregues de acordo com a **conta dona** do recurso. Uma cobrança ou assinatura criada com a chave de uma subconta pertence à subconta. O evento vai para: 1. Os endpoints cadastrados na conta dona, filtrados por `enabled_events` (lista vazia recebe todos). 2. Os endpoints da conta master (MerchantMaster) cadastrados com a opção de incluir subcontas (`include_submerchants: true`), quando a dona é uma subconta. Essa opção só existe para contas master com Connect habilitado. O payload traz o `merchant_id` (ou `merchantId`) da subconta, e é assim que a master identifica a origem. 3. O `postbackUrl` da cobrança, se ele foi informado. Assinaturas e saques não têm `postbackUrl`. Sem nenhum desses destinos, ninguém recebe o evento. Endpoints da master sem a opção de incluir subcontas não recebem eventos das subcontas. O desenho abaixo mostra como a Finvia escolhe os destinos de cada evento. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB EV(["Um evento acontece
cobrança, assinatura ou saque"]):::neutro DONA["Conta dona do recurso
quem criou com a chave dela"]:::finvia SQ{"Saque da master ou
de conta sem Connect?"}:::decisao NADA["Não gera webhook
acompanhe pela
listagem de saques"]:::neutro E1["Endpoints da conta dona
filtrados por enabled_events
lista vazia recebe todos"]:::lojista SUB{"A dona é
uma subconta?"}:::decisao E2["Endpoints da master com
include_submerchants: true
merchant_id indica a subconta"]:::lojista PB{"Cobrança com
postbackUrl?"}:::decisao E3["postbackUrl da cobrança
mesmos eventos de cobrança
e também o charge.updated"]:::lojista EV --> DONA --> SQ SQ -->|"sim"| NADA SQ -->|"não"| E1 DONA --> SUB SUB -->|"sim"| E2 DONA --> PB PB -->|"sim"| E3 ST(["Mudança de status
de uma subconta"]):::neutro E4["Só a URL de aviso de
status da subconta
sem envelope"]:::lojista ST --> E4 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` | Caso | Quem recebe | | - | - | | Cobrança da master com split para uma subconta | Só os destinos da master. A subconta que apenas participa do split não recebe o evento da cobrança | | Cobrança criada com a chave da subconta | Endpoints da subconta, endpoints da master com `include_submerchants: true` e o `postbackUrl` da cobrança | | Saque de subconta (`payout.*`) | Endpoints da subconta e endpoints da master com `include_submerchants: true` | | Saque da própria conta (master ou conta sem Connect) | Ninguém: não gera webhook. Acompanhe pela [listagem de saques](/referencia/saques/listar) | | Mudança de status de subconta | Só a URL de aviso de status da subconta. Veja [Webhooks de conta](/guias/webhooks/conta) | ## Configuração > [tab] Pelo painel > > **1. Selecione a conta** > > No [painel da Finvia](https://app.finvia.com.br), selecione a conta que vai receber os eventos (a master ou uma subconta). > > **2. Abra a área de webhooks** > > Vá em **Configurações** > **Webhooks**. > > **3. Informe a URL** > > Use uma URL pública com HTTPS, por exemplo `https://meusite.com.br/webhooks/finvia`. Na conta master com Connect, marque a opção de incluir subcontas se quiser receber também os eventos delas. > > O painel não tem seleção de eventos: o endpoint cadastrado por ele recebe todos os eventos (cobrança, assinatura e saque). > [tab] Pela API (endpoints) > > Use a rota [`POST /v1/webhook-endpoints`](/referencia/webhooks/criar-endpoint), com o id da conta em `merchantId` na query e o corpo em snake\_case. A API permite escolher os eventos em `enabled_events`. > > ```bash cURL theme={null} > curl -X POST "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD" \ > -u "$FINVIA_API_KEY:" \ > -H "Content-Type: application/json" \ > -d '{ > "url": "https://meusite.com.br/webhooks/finvia", > "enabled_events": ["charge.paid", "charge.refunded", "charge.blocked"], > "include_submerchants": true > }' > ``` > > A resposta é `201` sem corpo. Para saber o id do endpoint criado, use [`GET /v1/webhook-endpoints`](/referencia/webhooks/listar-endpoints). > [tab] Na cobrança (postback) > > Informe `postbackUrl` na criação da cobrança: > > ```json theme={null} > { > "amount": 100, > "currency": "BRL", > "customer": { "name": "Joao Silva", "email": "joao@email.com" }, > "paymentMethod": { "type": "pix", "expirationInDays": 1 }, > "items": [ > { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } > ], > "postbackUrl": "https://meusite.com.br/webhooks/finvia" > } > ``` O aviso de status de conta tem configuração própria, explicada em [Webhooks de conta](/guias/webhooks/conta). ## Eventos por canal Esta é a tabela de referência de eventos e canais. As demais páginas da documentação apontam para cá. | Evento | Endpoints da conta dona | Endpoints da master com `include_submerchants` | `postbackUrl` da cobrança | Formato | | - | - | - | - | - | | `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback`, `charge.blocked` | Sim | Sim, para cobranças de subconta | Sim | Envelope padrão | | `charge.updated` | **Não** | **Não** | Sim | Legado, sem `id` e sem `livemode`, camelCase | | `subscription.created`, `subscription.activated`, `subscription.renewed`, `subscription.payment_failed`, `subscription.cancelled`, `subscription.expired` | Sim | Sim, para assinaturas de subconta | Não se aplica | Envelope padrão | | `payout.approved`, `payout.rejected` | Sim, só para saques de subconta | Sim | Não se aplica | Envelope de saque | | Aviso de status de subconta | Não | Não | Não | Sem envelope. Vai para a URL de aviso de status da subconta | O que cada evento de cobrança significa: | Evento | Quando é enviado | | - | - | | `charge.created` | A cobrança foi criada. Uma cobrança que fica em `in_analysis` ou `authentication_required` na criação gera só este evento até o desfecho | | `charge.pending` | O processamento terminou em `pending` (por exemplo, Pix com QR Code gerado) | | `charge.paid` | O pagamento foi confirmado, na hora ou depois, pelo adquirente | | `charge.refused`, `charge.failed` | A cobrança foi recusada (`refused`) ou falhou (`failed`) na criação ou ao final do 3DS gerenciado | | `charge.refunded` | O estorno foi concluído | | `charge.pre_chargeback` | Um alerta de pré-chargeback foi registrado | | `charge.blocked` | A cobrança foi bloqueada (por exemplo, por MED ou chargeback em análise) | > [!WARNING] > > Recusas e falhas informadas **depois** pelo adquirente (uma cobrança que ficou em `in_analysis` e termina negada, um Pix cancelado ou expirado) não geram `charge.refused` nem `charge.failed`. Nesses casos sai só o `charge.updated` no `postbackUrl`. Para cobranças que ficam em `in_analysis` ou `pending`, acompanhe pelo `postbackUrl` ou consulte `GET /v1/charges/{id}`. ### Quando o charge.updated é enviado O `charge.updated` é o postback legado. Ele é enviado só ao `postbackUrl`, nas situações abaixo: * O adquirente informa uma mudança de status pelo webhook dele: pagamento, recusa ou falha assíncrona, estorno, chargeback. * O 3DS gerenciado termina em recusa ou falha. * A cobrança é bloqueada. * A cobrança recebe um alerta de pré-chargeback. Consequências práticas: * Um Pix pago gera `charge.paid` e também `charge.updated` no `postbackUrl`. * Endpoint de webhook nunca recebe `charge.updated`. Incluir esse nome em `enabled_events` não tem efeito. * O chargeback formalizado chega como `charge.updated` com `status: "chargeback"` e, quando o valor é revertido do saldo, também como `charge.refunded`. Detalhes em [Webhooks de cobrança](/guias/webhooks/cobranca#chargeback-formalizado). * A liberação de um bloqueio não gera evento nenhum. ## Formato por família Os formatos dos webhooks variam por família de evento. O formato atual é mantido por compatibilidade com integrações em produção, então escreva o parser seguindo esta tabela. | Família | Envelope | Chaves de `data` | Exceções | | - | - | - | - | | Cobrança: `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback`, `charge.blocked` | `{ id, event, livemode, data }` | snake\_case no primeiro nível (`psp_ref_id`, `merchant_id`, `payment_details`, `is_test`, `anticipation_fee_estimated`) | Os objetos aninhados mantêm o formato em que foram gravados, em camelCase: `payment_method` de cartão, `shipping_address`, `tracking_info`, `three_ds`, `freight_details` e `payment_details` do Pix. `metadata` volta exatamente como você enviou | | Cobrança legada: `charge.updated` | `{ event, data }`, sem `id` e sem `livemode` | camelCase em todos os níveis (`pspRefId`, `isBlocked`, `isTest`) | As chaves de `metadata` também são convertidas para camelCase (veja [Metadata](/guias/cobrancas/visao-geral#metadata)). Traz mais campos que o envelope padrão | | Assinatura: `subscription.*` | `{ id, event, livemode, data }` | snake\_case (`merchant_id`, `current_period_end`, `charge.charge_id`, `failure_reason`) | O objeto `trial` usa camelCase (`startDate`, `endDate`, `convertedAt`). `metadata` volta como foi enviada | | Saque: `payout.*` | `{ id, event, data }`, sem `livemode` | camelCase | O `id` da raiz é o id do saque e se repete nos eventos do mesmo saque. `amount`, `payoutFee` e `netAmount` chegam como texto decimal | | Aviso de status de conta | Sem envelope | camelCase (`merchantId`, `status`, `date`, `rejectionReason`) | Não tem nome de evento | | Respostas da API REST | Não se aplica | camelCase | Em `GET /v1/charges/{id}`, as chaves de `metadata` voltam em camelCase | > [!TIP] > > **Para o desenvolvedor:** no `charge.updated`, use só os campos documentados. Ele traz campos a mais, que podem mudar sem aviso. Se você depende de uma chave de `metadata`, envie-a em camelCase (`orderId`): ela chega igual nos dois formatos. Veja [Metadata](/guias/cobrancas/visao-geral#metadata). ### Envelope padrão (cobranças e assinaturas) ```json theme={null} { "id": "evt_1XcN7hJ4uQ2pZ8eL6wS3kF9a", "event": "charge.paid", "livemode": true, "data": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "paid", "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "is_test": false } } ``` | Campo | O que é | | - | - | | `id` | Identificador do evento. Trate como texto opaco | | `event` | Nome do evento, como `charge.paid` ou `subscription.renewed` | | `livemode` | Nos eventos de cobrança, `false` indica cobrança de teste (`data.is_test: true`) | | `data` | O objeto do recurso (a cobrança ou a assinatura). O exemplo acima foi resumido | ### Postback legado charge.updated Não tem `id` de evento nem `livemode`. O `data` é a cobrança em camelCase (`pspRefId`, `paymentMethod`, `isBlocked`, `isTest`). O formato completo está em [Webhooks de cobrança](/guias/webhooks/cobranca#postback-legado). ### Envelope de saque O `id` da raiz é o **id do saque** (o mesmo de `data.id`), não há `livemode` e os valores chegam como texto decimal com 8 casas: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "event": "payout.approved", "data": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "amount": "100.00000000", "currency": "BRL", "status": "approved", "payoutFee": "1.00000000", "netAmount": "99.00000000" } } ``` ### Aviso de status de subconta Chega sem envelope: o corpo é o próprio objeto, com `merchantId`, `status`, `date` e, em `rejected` e `correcting`, `rejectionReason`. Veja [Webhooks de conta](/guias/webhooks/conta). > [!WARNING] > > Um parser que espera snake\_case quebra no `charge.updated`, e um que espera `event` quebra no aviso de conta. Identifique a família antes de ler os campos: há `event`? Ele começa com `charge.`, `subscription.` ou `payout.`? É `charge.updated`? ## Teste e produção Os endpoints de webhook não têm modo: cada conta tem uma única lista de endpoints, que recebe os eventos de teste e os de produção. São de teste as cobranças criadas com a chave `sk_test_` e as pagas em link de pagamento criado em Modo Teste. O painel não tem uma lista separada de endpoints para o Modo Teste. | Família | Como reconhecer um evento de teste | | - | - | | Cobrança, envelope padrão | `livemode: false` e `data.is_test: true` | | `charge.updated` | `data.isTest: true` | | Assinatura | Não use `livemode` para separar teste de produção. As assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste | | Saque e aviso de conta | Não têm marcação de teste | > [!WARNING] > > O endpoint usado na homologação continua recebendo eventos de teste depois que você entra em produção. Descarte ou separe os eventos de cobrança com `livemode: false` antes de liberar pedidos. Para ter URLs diferentes por ambiente, use o `postbackUrl`, que é definido em cada cobrança. ## Como descartar eventos repetidos O mesmo evento pode chegar mais de uma vez. Grave a chave de cada evento recebido em um armazenamento persistente (banco de dados ou Redis) e ignore um evento cuja chave já exista. Esta é a regra que funciona com o corpo da mensagem: | Mensagem | Chave de deduplicação | Por quê | | - | - | - | | Envelope padrão (`charge.*` exceto `charge.updated`, e `subscription.*`) | `id` do envelope | É o identificador do evento | | `charge.updated` | `event` + `data.id` + `data.status` + `data.isBlocked` + `data.chargebackAlertRefunded` + `data.updatedAt` (os três últimos quando presentes) | Não há `id` de evento. O bloqueio mantém o `status` `paid` e muda só `isBlocked`. O alerta de pré-chargeback se distingue por `chargebackAlertRefunded`. O `updatedAt` muda a cada atualização da cobrança | | Saque (`payout.*`) | `id` da raiz + `event` | O `id` é o do saque e se repete nos eventos do mesmo saque. Cada saque gera no máximo um `payout.approved` ou um `payout.rejected` | | Aviso de status de subconta | Compare o `status` recebido com o último status gravado para aquela subconta. Se for igual, ignore | Não há envelope nem id. O campo `date` é a data de referência do status e pode se repetir: no desbloqueio, o aviso `active` traz a data original de aprovação | > [!TIP] > > **Para o desenvolvedor:** trate o `charge.updated` e o aviso de conta como atualização de estado. Gravar o mesmo estado duas vezes deixa o registro igual. Use a chave para não repetir efeitos colaterais, como e-mails ao cliente. Quando a entrega com retentativa entrar no ar, use o cabeçalho descrito em [Identificador e duplicidade](#identificador-e-duplicidade). ## Regras de negócio | Regra | Detalhe | | - | - | | Confirmação de recebimento | Só uma resposta `2xx` em até 10 segundos conta como entregue. Redirecionamentos não são seguidos | | Entrega repetida | O mesmo evento pode chegar mais de uma vez. Use a [receita de deduplicação](#como-descartar-eventos-repetidos) | | Sem assinatura HMAC | As mensagens não trazem cabeçalho de assinatura. Confirme os dados na API antes de ações críticas | | HTTPS | Use sempre HTTPS na URL de recebimento. Endereços internos e reservados não são aceitos no cadastro do endpoint | | Filtro de eventos | `enabled_events` só existe pela API e vale só para endpoints. Lista vazia recebe todos | | Teste e produção | A mesma lista de endpoints recebe os dois. Separe por `livemode` e `is_test` | > [!WARNING] > > Não libere produto, acesso ou saldo só com base no corpo do webhook. Como não há assinatura HMAC, qualquer pessoa que descubra a sua URL consegue enviar um POST com aparência de evento. Antes de uma ação crítica, consulte o recurso na API (por exemplo, `GET /v1/charges/{id}`) e use o status que a API devolver. ## Passo a passo O seu endpoint precisa: 1. Aceitar requisições `POST` na URL configurada. 2. Ler o corpo JSON e identificar a família do evento. 3. Responder com status `2xx` **antes** de executar lógica pesada. 4. Descartar eventos repetidos com a [receita de deduplicação](#como-descartar-eventos-repetidos). 5. Processar o evento de forma assíncrona, confirmando o status na API. O desenho abaixo mostra o receptor recomendado: responder rápido, descartar repetidos e confirmar na API antes de agir. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(234,243,255) Finvia participant F as Finvia API end box rgb(243,245,248) Sua aplicação participant R as Seu endpoint participant DB as Banco de chaves participant Q as Fila e worker end F->>R: POST com o evento em JSON R->>R: Identifica a família do evento R->>DB: Grava a chave de deduplicação alt Chave nova DB-->>R: Gravada R-->>F: 2xx em até 10 segundos R-)Q: Enfileira o evento Q->>F: GET /v1/charges/{id} F-->>Q: Status atual da cobrança Note over Q: Libera o pedido só se a API confirmar o status else Chave já existe DB-->>R: Já recebido R-->>F: 2xx, sem processar de novo end Note over R,DB: Envelope padrão usa o id do evento como chave. Saque, charge.updated e aviso de conta têm receita própria ``` ### Exemplo em Node.js (Express) O exemplo grava a chave de deduplicação no banco (idempotência persistente) e usa uma fila simples em memória para processar fora da requisição. Em produção, troque a fila em memória por uma fila do seu ambiente (Redis, SQS, RabbitMQ ou similar), para não perder eventos se o processo reiniciar. ```javascript Node.js theme={null} // webhook.mjs (Node.js 18+, ESM) import express from 'express'; import db from './db.js'; // seu módulo de banco; tabela webhook_events (event_key TEXT PRIMARY KEY, received_at TIMESTAMP) const API_URL = 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const app = express(); app.use(express.json()); // Receita de deduplicação pelo corpo (veja "Como descartar eventos repetidos"). // Devolve null para o aviso de conta, que é tratado por comparação de status. function dedupKey(body) { const event = body.event ?? ''; if (event.startsWith('payout.')) return `payout:${body.id}:${event}`; if (event === 'charge.updated') { const d = body.data ?? {}; return ['charge.updated', d.id, d.status, d.isBlocked ?? '', d.chargebackAlertRefunded ?? '', d.updatedAt ?? ''].join(':'); } if (event && body.id) return `evt:${body.id}`; return null; } // Fila simples em memória (exemplo). Em produção, use uma fila persistente. const queue = []; let working = false; async function runQueue() { if (working) return; working = true; while (queue.length) { const evt = queue.shift(); try { await handleEvent(evt); } catch (err) { console.error('Falha ao processar evento', evt.event ?? 'conta', err); // Registre para reprocessar depois } } working = false; } async function getCharge(id) { const res = await fetch(`${API_URL}/v1/charges/${id}`, { headers: { Authorization: `Basic ${credentials}` }, }); return res.json(); } async function handleEvent(body) { if (!body.event) { // Aviso de status de conta: aplique só se o status mudou const atual = await db.sellers.getStatus(body.merchantId); if (atual !== body.status) await db.sellers.setStatus(body.merchantId, body.status, body.rejectionReason); return; } if (body.event === 'charge.paid' && body.livemode === true) { // Confirma na API antes de liberar const charge = await getCharge(body.data.id); if (charge.status === 'paid') { await db.orders.markPaid(body.data.id); } } // Trate as demais famílias aqui } app.post('/webhooks/finvia', async (req, res) => { const body = req.body; const key = dedupKey(body); const inserted = key ? await db.query( 'INSERT INTO webhook_events (event_key, received_at) VALUES ($1, NOW()) ON CONFLICT DO NOTHING', [key] ) : { rowCount: 1 }; // Responde rápido, mesmo para eventos repetidos res.status(200).send('OK'); if (inserted.rowCount === 0) return; // já recebido queue.push(body); runQueue(); }); app.listen(3000); ``` ### Exemplo em PHP ```php PHP theme={null} prepare('INSERT INTO webhook_events (event_key, payload, status) VALUES (?, ?, ?) ON CONFLICT DO NOTHING'); $stmt->execute([$key, $payload, 'pending']); $isNew = $stmt->rowCount() > 0; // Responde rápido http_response_code(200); echo 'OK'; // Libera a conexão com a Finvia antes de processar (PHP-FPM) if (function_exists('fastcgi_finish_request')) { fastcgi_finish_request(); } if ($isNew) { // Uma rotina agendada (cron ou worker) lê os registros 'pending', // confirma o status na API e executa a regra de negócio. } ``` ### Valide consultando a API ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/charges/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` Se o status devolvido pela API não confirmar o evento, não execute a ação e registre o caso para análise. ## Entrega e retentativas **Em validação (V-58):** esta seção inteira, com retentativas, cabeçalhos `X-Webhook-*` e deduplicação pelo cabeçalho, entra no ar junto com o deploy da retentativa automática. A aplicação aos webhooks de saque será confirmada junto com a mudança do webhook de saque (V-16). A política abaixo vale para os endpoints de webhook, para o `postbackUrl` da cobrança e para a URL de aviso de status de conta. ### O que conta como entregue A notificação é considerada entregue quando o seu servidor responde com status `2xx` (de `200` a `299`) em até 10 segundos. Qualquer outro resultado conta como falha e gera nova tentativa: erro de conexão, falha de DNS, tempo esgotado, redirecionamento (`3xx`, que não é seguido), `4xx` ou `5xx`. ### Retentativas * São até 8 tentativas por destino, e a primeira é imediata. * As seguintes acontecem com intervalos de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas e 24 horas entre uma tentativa e a próxima, cerca de 45 horas no total. Os horários podem variar alguns minutos. * Se o seu servidor responder `429` ou `503` com o cabeçalho `Retry-After`, a próxima tentativa respeita esse prazo, até no máximo 1 hora a mais, sem aumentar o número de tentativas. Depois da última tentativa, a notificação fica registrada como não entregue e pode ser reenviada mediante solicitação ao suporte. O reenvio usa o mesmo identificador do evento. O desenho abaixo mostra a sequência de tentativas que entra no ar com o deploy da retentativa (V-58). ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB INI(["Evento a entregar
regra após o deploy (V-58)"]):::neutro G1["Tentativa 1: imediata
Tentativa 2: 1 min depois
Tentativa 3: 5 min depois"]:::alerta G2["Tentativa 4: 30 min depois
Tentativa 5: 2 h depois
Tentativa 6: 6 h depois"]:::alerta G3["Tentativa 7: 12 h depois
Tentativa 8: 24 h depois
cerca de 45 h no total"]:::alerta OK(["Entregue
2xx em até 10 s
encerra as tentativas"]):::ok FIM["Não entregue
reenvio pelo suporte,
com o mesmo id de evento"]:::erro INI --> G1 G1 -->|"falhou"| G2 G2 -->|"falhou"| G3 G3 -->|"falhou"| FIM G1 -.->|"2xx"| OK G2 -.->|"2xx"| OK G3 -.->|"2xx"| OK classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` Uma resposta `429` ou `503` com `Retry-After` pode alongar a espera até a próxima tentativa, sem aumentar o número de tentativas. ### Cabeçalhos enviados | Cabeçalho | Conteúdo | | - | - | | `X-Webhook-Event-Id` | Identificador do evento, igual em todas as tentativas | | `X-Webhook-Delivery-Id` | Identificador da entrega para aquele destino | | `X-Webhook-Attempt` | Número da tentativa (`1` a `8`; reenvios manuais terminam em `-manual`) | | `X-Webhook-Event` | Nome do evento | ### Identificador e duplicidade A entrega é garantida pelo menos uma vez: em casos raros, a mesma notificação pode chegar mais de uma vez. Responda `2xx` assim que receber e processe depois. Use o cabeçalho `X-Webhook-Event-Id` como chave de deduplicação. Ele é o mesmo em todas as tentativas de uma notificação e no reenvio feito pelo suporte. | Mensagem | Chave com o cabeçalho | Correspondência no corpo | | - | - | - | | Cobrança e assinatura (envelope padrão) | `X-Webhook-Event-Id` | O mesmo valor está no campo `id` do corpo | | Saque (`payout.*`) | `X-Webhook-Event-Id` | Nenhuma: o `id` do corpo é o id do saque | | `charge.updated` | `X-Webhook-Event-Id` | Nenhuma: o corpo não tem `id`. Sem o cabeçalho, use a combinação de campos da [receita pelo corpo](#como-descartar-eventos-repetidos) | | Aviso de status de conta | `X-Webhook-Event-Id` | Nenhuma: o corpo não tem `id` | ```javascript Node.js theme={null} // Prefira o cabeçalho; sem ele, caia na receita pelo corpo const key = req.get('X-Webhook-Event-Id') ?? dedupKey(req.body); ``` ### Ordem A ordem de entrega não é garantida. Um `charge.paid` pode chegar antes do `charge.pending` da mesma cobrança, por exemplo. Para saber o estado atual, use o status do próprio objeto ou consulte a API (`GET /v1/charges/{id}`, `GET /v1/subscriptions/{id}`, `GET /v1/submerchants/{merchantId}`). ### Endpoints com falha Endpoints com falhas repetidas não são desativados automaticamente. Corrija o destino para que as próximas tentativas sejam bem-sucedidas. ## Como testar ### Ferramentas | Ferramenta | Para que serve | | - | - | | ngrok | Expor o seu servidor local na internet durante o desenvolvimento | | webhook.site | Ver o corpo exato que a Finvia envia, sem escrever código | | Postman | Enviar manualmente um payload de exemplo para o seu endpoint | ```bash theme={null} # Instalar o ngrok npm install -g ngrok # Expor a porta local ngrok http 3000 # Use a URL gerada (ex.: https://abc123.ngrok.io/webhooks/finvia) no endpoint ou no postbackUrl ``` ### Simulador de eventos de teste [`POST /v1/charges/{id}/resend-webhook`](/referencia/cobrancas/reenviar-webhook-teste) simula um evento para uma cobrança de teste. Você escolhe o status (`paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis` ou `authentication_required`) e a rota gera um evento novo `charge.{status}`, com `id` novo, para o `postbackUrl` da cobrança e para os endpoints da própria conta. A cobrança não muda de status. ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "status": "paid" }' ``` * A rota só aceita cobranças de teste. Com uma cobrança de produção, a resposta é `403`. * Use-a para testar a conectividade e o tratamento de cada status. O payload simulado tem diferenças em relação ao real (traz campos a mais e não traz `anticipation_fee_estimated`), então não o use como referência de schema. * Cada chamada gera um evento com `id` diferente. Duas chamadas com o mesmo status produzem dois eventos distintos, e a deduplicação não descarta o segundo. ### Cenários da homologação | Código | Cenário | | - | - | | CHG-03 | Receber `charge.refused` (ou `charge.failed`) de uma recusa de cartão | | CHG-04 e CHG-05 | Receber `charge.pending` e `charge.paid` de um Pix | | CHG-07 | Receber `charge.refunded` após estorno | | CHG-08 | Receber um webhook e responder `2xx` em poucos segundos | | CHG-09 | Simular um evento no sandbox com o `resend-webhook` | | SUB-05 | Receber `subscription.created` e `subscription.activated` | | FC-08 | Receber o aviso de mudança de status de subconta | > [!TIP] > > A integração está pronta quando o seu endpoint responde `2xx` em poucos segundos, separa eventos de teste e de produção, ignora eventos repetidos e só executa ações depois de confirmar o status na API. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Nenhum webhook chega | URL incorreta, fora do ar ou inacessível pela internet (ex.: `localhost`) | Confira a URL do endpoint e teste com cURL de fora da sua rede | | Entrega contada como falha com o servidor no ar | O endpoint responde `3xx`, `4xx` ou `5xx`, ou demora mais de 10 segundos | Responda `2xx` primeiro e processe depois. Não use redirecionamento na URL | | O mesmo evento chega duas vezes ao mesmo tempo | A URL está cadastrada como endpoint e também enviada como `postbackUrl` | Use URLs diferentes ou deduplique | | `charge.updated` não chega nos endpoints | Esse evento vai só para o `postbackUrl` da cobrança | Informe `postbackUrl` nas cobranças | | A master não recebe eventos das subcontas | O endpoint da master não tem `include_submerchants: true` | Ative a opção no endpoint da master, pelo painel ou pela API | | A subconta não recebe o evento de uma venda com split | O evento vai só para a conta dona da cobrança | Trate o evento nos destinos da conta dona da cobrança | | Eventos de teste liberando pedidos em produção | A lista de endpoints é a mesma nos dois ambientes | Descarte eventos de cobrança com `livemode: false` | | Parser quebra em alguns eventos | Diferença de formato (snake\_case, camelCase, sem envelope) | Siga a tabela de [formato por família](#formato-por-família) | ## Perguntas frequentes > [accordion] Preciso usar webhook e postback ao mesmo tempo? > > Não é obrigatório. O endpoint de webhook cobre as cobranças, assinaturas e saques da conta. O postback serve quando você precisa de uma URL diferente por cobrança ou quer receber o `charge.updated` (chargeback formalizado, recusas assíncronas), que só chega por esse canal. > [accordion] Como sei que o webhook veio da Finvia? > > As mensagens não têm assinatura HMAC. Trate o webhook como um aviso de que algo mudou e confirme o status consultando a API com a sua chave secreta antes de agir. > [accordion] O QR Code do Pix vem no webhook? > > O webhook de cobrança Pix traz `payment_details` com o código copia e cola e a imagem do QR Code. Para mostrar o QR Code ao cliente, use a resposta de `POST /v1/charges`, que chega antes de qualquer webhook. > [accordion] Tenho uma lista de endpoints para teste e outra para produção? > > Não. A lista é uma só e recebe os dois tipos de evento. Nos eventos de cobrança, `livemode` vem `false` e `data.is_test` vem `true` quando a cobrança é de teste. No `charge.updated`, use `data.isTest`. > [accordion] Como escolho os eventos que um endpoint recebe? > > Pela API, no campo `enabled_events` de [`POST /v1/webhook-endpoints`](/referencia/webhooks/criar-endpoint) ou de [`PUT /v1/webhook-endpoints/{webhookId}`](/referencia/webhooks/atualizar-endpoint). Lista vazia recebe todos. O painel sempre cadastra o endpoint para todos os eventos. > [accordion] Perdi eventos enquanto meu servidor estava fora. E agora? > > Consulte os recursos pela API para reconciliar: [listagem de cobranças](/referencia/cobrancas/listar), [assinaturas](/referencia/assinaturas/listar), [saques](/referencia/saques/listar) e [subcontas](/referencia/fast-connect/listar-subcontas). A política de novas tentativas está em [Entrega e retentativas](#entrega-e-retentativas). ## Veja também > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos, campos e payloads de cobrança. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Ativação, renovação, falha e cancelamento. > [card] [Webhooks de saque](/guias/webhooks/saque) > > Aprovação e rejeição de saques de subcontas. > [card] [Webhooks de conta](/guias/webhooks/conta) > > Status de aprovação das subcontas. > [card] [Criar endpoint de webhook](/referencia/webhooks/criar-endpoint) > > Cadastro pela API, com filtro de eventos. > [card] [Catálogo de eventos](/anexos/catalogo-de-eventos) > > Todos os eventos em uma página. # Checklist de go-live Source: https://docs.fastpaybrasil.com/homologacao/checklist-go-live O que conferir na virada para produção: chave de produção, domínios, webhooks, tratamento de status, valores, segurança, monitoramento e um checklist por funcionalidade. Com a homologação concluída, a virada para produção é uma troca de chave. Antes dela, confira o que só aparece com dinheiro real: permissões, segredos, endpoints públicos, monitoramento e o plano para disputas. Use esta página como lista de verificação, item por item, antes de liberar o primeiro cliente real. > [!NOTE] > > **Para o negócio:** a API não tem trava técnica de homologação: a chave de produção existe assim que a conta é aprovada. Por isso, a decisão de virar é sua, e o roteiro de homologação, acompanhado pela equipe Finvia, é a etapa recomendada antes dela. Este checklist ajuda a não esquecer o que fica fora dos cenários: quem gerou a chave, onde ela está guardada, quem acompanha disputas e o que fazer se algo sair do ar. O desenho abaixo resume a virada para produção: o que conferir antes, a troca de chave e o que fazer depois. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB H(["Homologação concluída
evidências enviadas"]):::ok subgraph ANTES["Antes da virada"] K["Chave de produção
de Owner ou Manager"]:::lojista W["Webhooks de produção
em HTTPS, eventos de
teste descartados"]:::lojista U["URLs e domínios
acessíveis"]:::lojista end T["Troque sk_test_ por sk_
e pk_test_ por pk_
a URL continua a mesma"]:::finvia subgraph DEPOIS["Depois da virada"] R["Transação real de valor
baixo em cada método"]:::lojista M["Acompanhe as
primeiras horas"]:::lojista D["Desligue o que era
só de teste"]:::lojista end OK(["Virada concluída
com rastreio pelo id"]):::ok H --> K H --> W H --> U K --> T W --> T U --> T T --> R --> M --> D --> OK style ANTES fill:#F7F9FC,stroke:#D5DCE6 style DEPOIS fill:#F7F9FC,stroke:#D5DCE6 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` ## Antes da virada **1. Evidências da homologação conferidas** Os cenários das funcionalidades que você integrou têm evidência e resultado igual ao esperado, e as evidências foram enviadas ao suporte da Finvia. Veja o [roteiro de homologação](/homologacao/roteiro). **2. Chave de produção do usuário certo** No painel, em **Configurações > Chave de API**, aba **Produção**, clique em **Revelar chave** e informe o código enviado ao seu e-mail. O par `sk_`/`pk_` de produção é criado automaticamente no cadastro ou na aprovação da conta e pertence ao proprietário, com acesso a todas as rotas. Se usar uma chave gerada por outro usuário, ela age com as permissões dele: use um usuário **Owner** ou **Manager** (veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave)). Guarde a chave direto no cofre de segredos ou na variável de ambiente do servidor de produção. **3. Troca de sk\_test\_ para sk\_** A URL é a mesma para sandbox e produção. O ambiente é definido só pela chave: troque a chave de teste (`sk_test_`) pela de produção (`sk_`), e a pública de teste (`pk_test_`) pela de produção (`pk_`), onde ela for usada. Se você usa subcontas do Connect, busque as chaves de produção de cada subconta com `GET /v1/submerchants/{id}/api-keys`. **4. URL da API e domínios** Confirme que a sua configuração usa estes endereços e que eles estão acessíveis a partir dos seus servidores e do navegador dos seus clientes: | Para quê | Endereço | | - | - | | API | `https://api-global.fastpaybrasil.com` | | Painel | `https://app.finvia.com.br` | | Documentação | `https://docs.fastpaybrasil.com` | | SDK de 3D Secure via CDN | `https://js.fastpaybrasil.com/security-sdk.min.js` | No 3DS gerenciado, leve o comprador ao endereço recebido em `authenticationUrl`, sem montar nem alterar a URL. As URLs de documentos de sócios são assinadas, expiram em 1 hora e têm o domínio do provedor de armazenamento: não fixe esse domínio nem guarde a URL. **5. Webhooks de produção** Os endpoints de webhook não têm modo: a sua conta tem uma única lista, que recebe eventos de teste e de produção, e o painel não tem uma lista separada para o Modo Teste. O endpoint usado na homologação continua recebendo eventos de teste depois da virada. Por isso: * descarte ou separe os eventos de teste: `livemode: false` e `data.is_test: true` no envelope padrão de cobrança, `data.isTest` no `charge.updated`; * se quiser URLs diferentes por ambiente, use a `postbackUrl`, que é definida em cada cobrança; * confira se a `postbackUrl` enviada nas cobranças de produção aponta para o endereço de produção, sempre em **HTTPS**; * retire túneis de desenvolvimento (como ngrok) da configuração. **6. Simulação de webhook só no sandbox** `POST /v1/charges/{id}/resend-webhook` é um simulador, disponível só para cobranças de teste. Ele gera um evento novo, com `id` novo, a cada chamada. Rotinas que dependiam dele não funcionam em produção. ## Checklist geral ### Credenciais e segurança * [ ] Chave de produção (`sk_`) do proprietário ou gerada por Owner ou Manager * [ ] Chave secreta só no servidor, em variável de ambiente ou cofre de segredos; nunca no código, no repositório, no navegador ou no aplicativo * [ ] Chave pública (`pk_`) usada só nas rotas que pedem por ela (Apple Pay `validate-merchant`, rotas de 3D Secure e SDK) * [ ] Chaves de teste e de produção separadas por ambiente; a chave de produção nunca é usada em testes * [ ] Chaves das subcontas guardadas em cofre, associadas a cada subconta * [ ] Processo de **troca de chave** definido: quem pede a troca ao suporte, onde atualiza a `sk_` no servidor e a `pk_` no front-end (as duas mudam juntas), e troca imediata em caso de suspeita de vazamento * [ ] Acesso aos logs restrito ao time responsável ### Webhooks * [ ] Endpoints em HTTPS, acessíveis pela internet, sem autenticação que bloqueie a Finvia * [ ] Endpoint responde com status **`2xx`** em até 10 segundos, antes de processar a lógica pesada. Qualquer outra resposta, inclusive redirecionamento, conta como falha de entrega (veja a política de entrega em [Webhooks](/guias/webhooks/visao-geral)) * [ ] **Idempotência persistente**: os `id` de evento já processados ficam em banco de dados ou cache persistente * [ ] **Validação via API**: antes de liberar produto, acesso ou dinheiro, o sistema confirma o estado com `GET /v1/charges/{id}`, porque os webhooks não têm assinatura HMAC * [ ] Tratamento do `charge.updated` (só no `postbackUrl`, sem `id` e `livemode`, campos em camelCase), deduplicado pela combinação `event` + `data.id` + `data.status` + `data.isBlocked` + `data.chargebackAlertRefunded` + `data.updatedAt`, como na [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos) * [ ] Tratamento dos formatos de campos: snake\_case no primeiro nível de `data` no envelope padrão (objetos aninhados em camelCase, `metadata` como enviada), camelCase na API, no `charge.updated`, nos avisos de conta e nos eventos de saque * [ ] Eventos de teste (`livemode: false`) descartados ou separados no ambiente de produção * [ ] Rate limiting no endpoint, para proteção contra abuso * [ ] Rotina de conferência pela API para eventos que não chegaram, em especial saques (pela listagem) ### Tratamento de status * [ ] Cobrança: `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`, `pre_chargeback` e `chargeback`; bloqueio por `isBlocked` * [ ] `authentication_required` tratado já na resposta da criação, com o comprador levado à `authenticationUrl` * [ ] Recusa no cartão tratada pela resposta da criação, com o motivo de `reason`; `charge.refused` e `charge.failed` tratados como complemento * [ ] Estorno: a resposta hoje traz `refunded`; um status diferente cai no caso padrão * [ ] Assinatura: `active`, `pending_activation`, `cancelled` e `expired` * [ ] Subconta: `pending`, `pre_approved`, `correcting`, `active`, `rejected`, `blocked` e `inactive` * [ ] Saque: `pending`, `approved` (aprovado e enviado para pagamento) e `rejected` * [ ] Um caso padrão (`default`) que registra status ou eventos desconhecidos sem quebrar o processamento ### Valores e dados * [ ] Todos os valores em **reais**: `amount`, `unit_price`, `price` do plano e `amount` do saque (`10` = R\$ 10,00) * [ ] `shippingAddress` em toda venda com item `physical`, com `postalCode`, `addressLine1`, `city`, `state` e `country` em 3 letras (`BRA`) * [ ] Valores de saque (`amount`, `payoutFee`, `netAmount`) e `splitPercentage` convertidos de texto decimal para número antes de calcular * [ ] Percentuais de split calculados sobre o valor líquido, com taxas consultadas na API ### Logs e privacidade * [ ] Logs **sem dados de cartão**: número completo, CVV e validade nunca são gravados * [ ] Logs sem a chave secreta e sem o cabeçalho `Authorization` * [ ] Logs com o `id` de cada cobrança, assinatura, subconta e saque, para rastrear casos com o suporte * [ ] URLs assinadas de documentos de sócios não são guardadas (expiram em 1 hora) ### Duplicidade e falhas de rede * [ ] A API não tem `Idempotency-Key`: depois de um timeout na criação, o sistema segue o [procedimento de timeout](/primeiros-passos/paginacao-ordenacao-idempotencia#procedimento-depois-de-um-timeout-ao-criar-cobrança) (identificador do pedido em `metadata`, webhook `charge.created` e busca por `createdAtStart`, `createdAtEnd` e `searchFor`) antes de criar de novo * [ ] O `id` de cada cobrança é salvo no seu sistema no momento da criação, porque a listagem não busca por `metadata` * [ ] Timeout de cliente generoso na criação de cobrança (por exemplo, 60 segundos) * [ ] `GET /v1/charges/{id}` com corpo vazio tratado como "não encontrada" * [ ] Antes de reenviar um estorno, o sistema consulta a cobrança; se ela já estiver `refunded`, não envia de novo ### Monitoramento * [ ] Alerta para aumento de respostas `401`, `403`, `422` e `500` da API * [ ] Alerta para endpoint de webhook fora do ar ou respondendo com status fora de `2xx` * [ ] Painel interno com cobranças `pending` antigas, assinaturas com `payment_failed` e saques pendentes * [ ] Fechamento diário comparando cobranças pagas na Finvia com pedidos pagos no seu sistema ### Plano para chargeback e MED O MED (Mecanismo Especial de Devolução) é o mecanismo do Pix que permite à instituição de quem pagou pedir a devolução em caso de fundada suspeita de fraude ou falha operacional. O chargeback é a contestação de uma compra no cartão. * [ ] Tratamento de `charge.blocked` (cobrança continua `paid`, com `isBlocked: true`): marcar como em disputa. O evento vai aos endpoints e à `postbackUrl` * [ ] Rotina que consulta as cobranças bloqueadas (`GET /v1/charges?status=blocked`), porque a liberação do bloqueio não gera webhook; use `isBlocked` para saber se continua bloqueada * [ ] Tratamento de `charge.pre_chargeback` e de `charge.refunded` com `chargeback_alert_refunded: true` (alerta com estorno) * [ ] `postbackUrl` enviada nas cobranças de cartão, porque o chargeback formalizado chega nela como `charge.updated` com `status: "chargeback"`; quando o valor é revertido do saldo, chega também `charge.refunded`. Confirme com `GET /v1/charges/{id}` * [ ] Responsável definido para reunir as evidências da venda (comprovante de entrega, registro de acesso, comunicação com o cliente) e enviá-las em resposta ao e-mail de alerta de chargeback ou MED, dentro do prazo indicado nele. O alerta vai para o e-mail da conta (no Connect, da conta master): garanta que ele chega a esse responsável. Não existe envio de defesa pela API * [ ] Política interna de reembolso alinhada com o atendimento Detalhes em [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med). ## Checklist por funcionalidade > [tab] Pix > > * [ ] Validade definida com `expirationInDays` (mínimo `1`) ou `expirationInSeconds` (mínimo `900`) > * [ ] QR Code exibido a partir de `qrCodeBase64`, com `copyPaste` quando a imagem vier `null` > * [ ] Pedido marcado como pago só com `charge.paid` e status confirmado na API > * [ ] Rotina para Pix não pago ao fim da validade, com consulta antes de cancelar o pedido (a expiração não gera evento nos endpoints; ela chega à `postbackUrl` como `charge.updated`) > * [ ] Cenários CHG-04 a CHG-09 concluídos > [tab] Cartão > > * [ ] `number` só com dígitos, `expirationYear` com 4 dígitos, `cvv` com pelo menos 3 > * [ ] `installments` de `1` a `12` > * [ ] Recusa tratada na resposta, com outra forma de pagamento oferecida > * [ ] Dados do cartão trafegam só entre o navegador, o seu servidor e a Finvia, em HTTPS, sem gravação > * [ ] Se usar 3DS gerenciado: `browser` com `userAgent` e `ipAddress`, e tratamento de `authentication_required` > * [ ] Cenários CHG-01, CHG-02, CHG-03, CHG-06 a CHG-08 e CHG-10 concluídos > [tab] Cartão salvo > > * [ ] Cliente com e-mail e CPF ou CNPJ antes de registrar o cartão > * [ ] Cartão com `status` `active` > * [ ] CVV coletado do comprador a cada cobrança > * [ ] Cartão usado só pela conta que o registrou > * [ ] Cartões salvos durante a homologação revisados: o cofre é o mesmo para teste e produção, e um `cardTokenId` de teste cobra de verdade com a chave de produção > * [ ] Cenários SUB-01 e SUB-02 concluídos > [tab] Apple Pay > > * [ ] Todos os hostnames de produção registrados e com `status` `verified` > * [ ] Arquivo de verificação servido sem extensão, em `text/plain`, sem redirecionamento > * [ ] Validação de sessão com a chave pública de produção > * [ ] `customer.document` coletado antes de abrir a folha de pagamento; moeda `BRL` > * [ ] `supportedNetworks` com `visa` e `masterCard` > * [ ] Cenários AP-01 a AP-06 concluídos > [tab] Assinaturas > > * [ ] Planos de produção criados em `BRL`, com a chave de produção > * [ ] Aviso ao comprador sobre a validação de R\$ 1,00 em planos com trial grátis > * [ ] Tratamento de `pending_activation`, `firstCharge.pending` e `CARD_VALIDATION_FAILED` > * [ ] Acesso controlado por `subscription.activated`, `renewed`, `payment_failed`, `cancelled` e `expired` > * [ ] Acesso mantido até o fim do período pago no cancelamento regular > * [ ] Assinatura de homologação cancelada (cenário SUB-06) > * [ ] Cenários SUB-01 a SUB-06 concluídos > [tab] Connect e split > > * [ ] Connect habilitado na conta de produção > * [ ] Subcontas de produção criadas com a chave de produção e com KYC aprovado > * [ ] Chaves de produção de cada subconta obtidas e guardadas > * [ ] Cobranças criadas com a chave da subconta que origina a venda > * [ ] Percentual de split calculado com `fees-info` de produção e soma até 100% > * [ ] Tratamento dos avisos de status das subcontas > * [ ] Cenários FC-01 a FC-08 e SPL-01 a SPL-06 concluídos > [tab] Saques > > * [ ] Autenticação Basic com a `sk_` de um perfil com permissão de saque (chave de Desenvolvedor recebe `403`) > * [ ] Saque da própria conta em `POST /v1/payout-requests` com `externalAccountDetails` `{ "type": "pix" }`; `201` sem corpo tratado, com o `id` buscado na listagem > * [ ] CNPJ da conta (e de cada subconta) cadastrado como chave Pix em uma conta bancária da empresa > * [ ] Valor em reais; na subconta, mínimo de R\$ 1,00 > * [ ] Subconta ativa, com CNPJ e taxa de saque configurados > * [ ] Eventos `payout.approved` e `payout.rejected` recebidos nos endpoints da subconta ou nos da master com a opção de incluir subcontas (saques da própria conta não geram webhook) > * [ ] Acompanhamento pela listagem `GET /v1/payout-requests` (`pending`, `approved`, `rejected`) > * [ ] Cenários FC-07 e, se aplicável, PAY-01 a PAY-07 conferidos ## Depois da virada **1. Faça uma transação real de valor baixo** Crie uma cobrança real de valor baixo em cada método integrado, confira o webhook, a baixa no seu sistema e o estorno. **2. Acompanhe as primeiras horas** Observe os alertas de erro da API e de entrega de webhooks. Confira no painel se os eventos estão sendo entregues com sucesso. **3. Desligue o que era só de teste** Remova endpoints de túnel, chaves de teste esquecidas em configuração de produção e rotinas que simulavam eventos com o reenvio de webhook do sandbox. > [!TIP] > > A virada está concluída quando a primeira transação real de cada método foi criada, notificada por webhook, conciliada no seu sistema e, no teste de estorno, devolvida, com todos os registros rastreáveis pelo `id`. ## Veja também > [card] [Roteiro de homologação](/homologacao/roteiro) > > Cenários e evidências. > [card] [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) > > Geração de chaves e permissões. > [card] [Erros e como tratar](/primeiros-passos/erros) > > Códigos HTTP e respostas de erro. > [card] [Webhooks](/guias/webhooks/visao-geral) > > Canais, idempotência e política de entrega. # Roteiro de homologação Source: https://docs.fastpaybrasil.com/homologacao/roteiro Cenários de teste por funcionalidade, o resultado esperado de cada um e as evidências que a equipe Finvia confere antes da virada para produção. A homologação é a etapa em que você executa no ambiente de testes (sandbox) os cenários das funcionalidades que integrou e guarda as evidências de cada um. Ela é recomendada antes de virar para produção e é acompanhada pela equipe Finvia: fale com o suporte da Finvia para agendar a homologação e enviar as evidências. A API não tem uma trava técnica de homologação. A chave de produção pode ser gerada no painel assim que a conta é aprovada, e as subcontas já nascem com credenciais. Mesmo assim, executar este roteiro é a forma de comprovar que a integração trata os caminhos de sucesso e de erro antes de receber clientes reais. Este roteiro diz **o que testar e o que comprovar**. O passo a passo técnico de cada recurso está nos guias e na referência da API, indicados em cada seção. > [!NOTE] > > **Para o negócio:** na homologação, a integração prova que trata pagamento aprovado, recusado e estornado, webhook recebido e valor em reais. Um cenário que falha aponta um problema que apareceria com clientes reais. Corrija antes de virar. ## Como usar O desenho abaixo mostra a jornada da homologação, da chave de teste até a liberação para o go-live. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB K(["Gere a chave de teste
com Owner ou Manager"]):::lojista Q{"O que você
integrou?"}:::decisao A["A · Cobrança
CHG-01 a 10"]:::neutro B["B · Split
SPL-01 a 06"]:::neutro C["C · Connect
FC-01 a 08"]:::neutro D["D · Apple Pay
AP-01 a 06"]:::neutro E["E · Saques
PAY-01 a 07"]:::alerta F["F · Cartão salvo
e assinaturas
SUB-01 a 06"]:::alerta EV["Guarde as evidências
requisição, resposta, id
e webhook com 2xx"]:::lojista SUP["Envie ao suporte
uma linha por cenário"]:::lojista FIN{"A equipe Finvia
aponta problema?"}:::decisao FIX["Corrija a integração
e envie nova evidência"]:::erro GO(["Siga para o
checklist de go-live"]):::ok K --> Q Q --> A Q --> B Q --> C Q --> D Q --> E Q --> F A --> EV B --> EV C --> EV D --> EV E --> EV F --> EV EV --> SUP --> FIN FIN -->|"sim"| FIX FIX --> SUP FIN -->|"não"| GO classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Os cenários de saques (E) são uma conferência de contrato, porque não existe saque no Modo Teste. Os de assinatura (F) usam cartão real: cancele a assinatura no mesmo dia. **1. Gere a chave de teste** No painel, em **Configurações > Chave de API**, abra a aba **Teste** e gere o par `sk_test_`/`pk_test_`. Gere com um usuário Owner ou Manager: uma chave gerada por Desenvolvedor recebe `403` ao criar cobranças. Veja [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes#onde-obter-as-chaves). **2. Escolha as seções que se aplicam** Execute os cenários das funcionalidades que você integrou: **Cobrança sem split**, **Cobrança com split**, **Connect (subcontas)**, **Apple Pay**, **Saques (payout)** e/ou **Cartão salvo e assinaturas**. **3. Guarde as evidências de cada cenário** Para cada cenário, guarde: **corpo da requisição**, **corpo da resposta**, o **ID gerado** (cobrança, subconta ou saque) e, quando houver, o **registro do webhook recebido** e a **resposta HTTP que o seu endpoint devolveu**. **4. Envie as evidências ao suporte** Fale com o suporte da Finvia para agendar a homologação e enviar as evidências, organizadas por código de cenário. Veja a seção [Envio das evidências](#envio-das-evidências), no fim desta página. ## Convenções de evidência | Tipo | O que enviar | Por que | | - | - | - | | Requisição e resposta | JSON completo. Pode omitir dados de cartão: a Finvia não precisa do número do cartão (PAN) | Mostra que o corpo respeita o contrato e que a resposta foi tratada | | Webhook | Print ou log com o evento recebido e o **status `2xx`** que o seu endpoint respondeu | Prova que o endpoint recebe e confirma a entrega. Qualquer resposta fora de `2xx` conta como falha | | Identificadores | Sempre o `id` da cobrança, subconta ou saque | Permite à equipe Finvia rastrear o cenário nos registros dela | | Critério | Um cenário só é considerado **testado** com a evidência anexada | "Funcionou" sem evidência não comprova o cenário | > [!TIP] > > **Para o desenvolvedor:** registre requisição, resposta e webhooks em log desde o primeiro teste, com o `id` de cada objeto. Montar a evidência no fim, a partir do log, é mais rápido do que refazer cenários. Mascare dados de cartão e chaves antes de enviar. ### Cartões de teste No Modo Teste, o resultado da cobrança de cartão depende só do número. Envie só dígitos, sem espaços. | Número | Resultado | `status` / `reason` | | - | - | - | | `4444333322221111` | Aprovado | `paid` / `success` | | `4444333322221112` | Recusado | `refused` / `card_declined` | | Qualquer número terminado em `2222` | Pendente, sem confirmação posterior | `pending` / `pending` | | Qualquer outro número | Aprovado | `paid` / `success` | Nome, CVV e validade não mudam o resultado (use validade futura, com mês de 2 dígitos, ex.: `05`, e ano com 4, e CVV de 3 dígitos). As regras de 3D Secure e de antifraude da conta continuam valendo no Modo Teste. Para os cenários de recusa, use uma conta sem 3DS obrigatório; do contrário, a recusa pode vir dessas etapas, com outro `reason`. ## A. Cobrança sem split (cartão de crédito e Pix) Cenários para quem cria cobranças Pix ou de cartão de crédito. Referências: [Criar cobrança](/referencia/cobrancas/criar) · [Consultar cobrança](/referencia/cobrancas/consultar) · [Estornar cobrança](/referencia/cobrancas/estornar) · [Webhooks de cobrança](/guias/webhooks/cobranca) | Código | Cenário | Resultado esperado | Evidência a enviar | | - | - | - | - | | CHG-01 | Cobrança de cartão de crédito **aprovada à vista** (1x), com o cartão `4444333322221111` | Cobrança criada com status `paid`; webhook `charge.paid` recebido | Requisição + resposta + `id` + registro do webhook | | CHG-02 | Cobrança de cartão **parcelada** (ex.: 3x), com o cartão `4444333322221111` | Status `paid`; `installments` refletido | Requisição + resposta + `id` | | CHG-03 | Cobrança de cartão **recusada**, com o cartão `4444333322221112` | Status `refused` e `reason` `card_declined` **na própria resposta**; webhook `charge.refused` (ou `charge.failed`, se o status for `failed`) | Requisição + resposta mostrando `refused` e o motivo + registro do webhook | | CHG-04 | **Pix gerado** | Status `pending`; resposta traz copia e cola e QR Code; webhooks `charge.created` e `charge.pending` | Requisição + resposta (com copia e cola) + `id` + webhook | | CHG-05 | **Pix pago** no sandbox | Cerca de 5 segundos depois da criação, a cobrança passa sozinha para `paid`; webhook `charge.paid` | Registro do webhook `charge.paid` com o mesmo `id` retornado na criação | | CHG-06 | **Consulta** da cobrança (`GET /v1/charges/{id}`) | Retorna o status atual e os detalhes de pagamento | Resposta do GET | | CHG-07 | **Estorno total** de uma cobrança paga (use a do CHG-01 ou a do CHG-05) | Status `refunded`; webhook `charge.refunded` | Requisição de estorno + resposta + webhook | | CHG-08 | **Recebimento de webhook** | Seu endpoint recebe o evento e responde **`2xx`** em poucos segundos | Print/log do webhook recebido + status respondido | | CHG-09 | **Simulação de webhook (sandbox)** | Resposta `201` com `deliveries`; evento simulado recebido pelo seu endpoint | Resposta da simulação + log do evento recebido ([simular webhook](/referencia/cobrancas/reenviar-webhook-teste)) | | CHG-10 | **Item físico com endereço de entrega** | Sem `shippingAddress`, a API responde `400` com `Shipping info must be provided for merchants selling physical items.`; com o endereço, `201` | As duas requisições e respostas | > [!NOTE] > > Autenticação obrigatória em todos os cenários. O 3D Secure, quando aplicável à sua conta, é coberto pelos guias de [3D Secure](/guias/3d-secure/visao-geral). ### Por que cada cenário existe e como executar > [accordion] CHG-01 e CHG-02: aprovação à vista e parcelada > > Comprovam que o corpo da cobrança de cartão está completo (`number`, `holderName`, `expirationMonth`, `expirationYear` com 4 dígitos, `cvv`, `installments`) e que o seu sistema lê o `status` da resposta. O CHG-02 confirma que o parcelamento chega à cobrança: envie `installments` maior que 1 (de `1` a `12`) e mostre o valor refletido em `paymentDetails.installments`. > > **Rota:** `POST /v1/charges` com `paymentMethod.type` `credit_card` e o cartão `4444333322221111`. **Dica:** envie `amount` em reais (`10` = R\$ 10,00) e `postbackUrl` para já capturar o `charge.paid` do CHG-01. O parcelamento só funciona se a conta tiver taxa configurada para o número de parcelas; sem ela, a resposta é `422` com `Fees not configured`. > [accordion] CHG-03: recusa > > Comprova que o checkout trata a recusa a partir da resposta, mostrando uma mensagem ao comprador e oferecendo outra forma de pagamento. Use o cartão `4444333322221112`, em uma conta sem 3D Secure obrigatório. > > **Rota:** `POST /v1/charges`. A recusa vem na resposta síncrona e também no webhook `charge.refused` (status `refused`) ou `charge.failed` (status `failed`), enviado aos endpoints e à `postbackUrl`, no máximo uma vez por cobrança. **Dica:** trate a recusa pela resposta. O webhook é complementar e não traz o motivo; o motivo está em `reason`. > [accordion] CHG-04 e CHG-05: Pix gerado e pago > > O CHG-04 comprova que o seu sistema exibe o código copia e cola (`paymentDetails.copyPaste`) e o QR Code (`qrCodeBase64`, que pode vir `null`). O CHG-05 comprova que o pedido muda para pago quando chega o `charge.paid` com o mesmo `id`. > > **Rota:** `POST /v1/charges` com `paymentMethod.type` `pix` e `expirationInDays` (mínimo `1`) ou `expirationInSeconds` (mínimo `900`). No Modo Teste, o código Pix é fictício e não deve ser pago em aplicativo de banco: cerca de 5 segundos depois, a cobrança vira `paid` sozinha, `paidAt` é preenchido e chega o `charge.paid`. Os eventos de teste chegam com `livemode: false`. **Dica:** no sandbox todo Pix é aprovado. Se a cobrança não virar `paid` em alguns segundos, crie outra. A conta precisa ter Pix habilitado; sem isso, a resposta é `422` com `Fees not configured`. > [accordion] CHG-06: consulta > > Comprova que o seu sistema consegue conferir o estado real de uma cobrança. Isso é necessário porque os webhooks não têm assinatura HMAC: antes de liberar produto ou acesso, a integração confirma o status na API. > > **Rota:** `GET /v1/charges/{id}`. **Dica:** o campo `splits` só vem vazio em contas sem regra de split padrão. Se a sua conta tem uma regra padrão para a moeda e o método, `splits` vem preenchido mesmo sem `split` na criação. Para um `id` que não existe, a resposta hoje é `200` com corpo vazio. > [accordion] CHG-07: estorno total > > Comprova que o seu sistema estorna uma cobrança paga e reage ao `charge.refunded`. A API faz só estorno total, e cada cobrança aceita um único estorno. > > **Rota:** `POST /v1/refunds` com `chargeId` e `reason` (os dois obrigatórios). **Dica:** antes de repetir um estorno após timeout, consulte a cobrança: se já estiver `refunded`, não envie de novo. Um segundo pedido recebe `422` com `Já existe um reembolso para esta cobrança`, e uma cobrança que não está `paid` recebe `404` com `Cobrança não encontrada`. > [accordion] CHG-08 e CHG-09: recebimento e simulação de webhook > > O CHG-08 comprova que o endpoint aceita POST, responde rápido com status `2xx` e processa o evento depois. O CHG-09 comprova que o endpoint trata eventos de outros status e um evento repetido sem duplicar o efeito. > > **Rota da simulação:** `POST /v1/charges/{id}/resend-webhook`, com `status` no corpo (`paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis` ou `authentication_required`); funciona só para cobranças de teste. Ela não reenvia o evento original nem altera a cobrança: gera um evento novo `charge.{status}`, com `id` novo. **Dica:** como o `id` é novo, a proteção contra efeito duplicado vem da checagem do pedido (por exemplo, não liberar duas vezes um pedido já pago). > [accordion] CHG-10: item físico com endereço > > Comprova que o seu fluxo envia `shippingAddress` em toda venda com item `physical`. São obrigatórios `postalCode`, `addressLine1`, `city`, `state` e `country` (3 letras, ex.: `BRA`). `addressLine2` e `neighborhood` são opcionais. > > **Rota:** `POST /v1/charges` com itens `physical`. Sem `shippingAddress`, a API responde `400` antes de criar a cobrança, sem gerar `id` nem webhook: > > ```json theme={null} > { "message": "Shipping info must be provided for merchants selling physical items.", "error": "Bad Request", "statusCode": 400 } > ``` > > Se o endereço vier incompleto ou inválido, o erro também é `400`, com `message` em lista (ex.: `["shippingAddress.country must be a valid ISO31661 Alpha3 code"]`). **Dica:** a evidência é a requisição sem endereço com o `400` e a mesma requisição com o endereço com `201`. ## B. Cobrança com split Cenários para quem envia o campo `split` nas cobranças. Pré-requisito: os recebedores do split (`merchantId`) devem existir e pertencer ao seu grupo Connect. Na criação, o campo é `split` (singular), cada item com `merchantId` e `percentage` (0,01 a 100). Na consulta `GET /v1/charges/{id}`, o campo é `splits` (plural), e cada item traz: | Campo | O que é | | - | - | | `destinyMerchantId` | Conta recebedora (o `merchantId` enviado em `split`) | | `destinyMerchantName` | Nome fantasia da conta recebedora | | `splitPercentage` | Percentual, como texto decimal (ex.: `"30.00000000"`). Converta para número antes de comparar | | `splitAmount` | Valor exibido para o recebedor, número com 2 casas (truncado) | | `referenceAmount` | Base de cálculo: `net` (valor líquido, o padrão) ou `gross` (valor bruto, quando a conta é configurada assim) | Se a cobrança não traz `split`, a API aplica a regra de split padrão da conta para aquela moeda e método (em subconta sem regra própria, vale a da conta master). Nesse caso `splits` vem preenchido mesmo sem `split` na criação. Referências: [Cálculo de split](/guias/fast-connect/calculo-split) · [Criar cobrança](/referencia/cobrancas/criar) **Em validação (V-64):** split combinado com 3DS gerenciado tem um erro conhecido em correção. Não homologue essa combinação antes da correção. | Código | Cenário | Resultado esperado | Evidência a enviar | | - | - | - | - | | SPL-01 | Cobrança **com split para 1 recebedor** (ex.: 30%), aprovada | Status `paid`; `GET /v1/charges/{id}` retorna `splits` com `destinyMerchantId`, `splitPercentage` e `splitAmount` | Requisição (com `split`) + resposta + GET mostrando `splits` | | SPL-02 | Cobrança **com split para 2 ou mais recebedores** somando até 100% | Aprovada; `destinyMerchantId`, `splitPercentage` e `splitAmount` de cada recebedor conferem no GET | Requisição + GET com todos os `splits` | | SPL-03 | Split com **percentual inválido** (0, acima de 100, ou soma inconsistente) | A API **rejeita** com erro de validação | Requisição + resposta de erro (comprovar tratamento) | | SPL-04 | Split para **`merchantId` inexistente ou fora do grupo** | A API **rejeita** | Requisição + resposta de erro | | SPL-05 | **Conferência do valor** destinado a cada recebedor | `splitPercentage` igual ao enviado e `splitAmount` coerente com a base (valor líquido × percentual, ou um valor menor enquanto a simulação de antecipação estiver ativa) | `GET /v1/charges/{id}` com os valores de `splits` | | SPL-06 | Split em **Pix** e em **cartão parcelado** (se ambos forem usados) | Split aplicado corretamente nos dois métodos | Requisição + GET de cada método | ### Por que cada cenário existe e como executar > [accordion] SPL-01 e SPL-02: um e vários recebedores > > Comprovam que a divisão chega à cobrança e pode ser conferida depois. A soma dos percentuais não pode passar de 100%; o que sobra fica com quem originou a venda. > > **Rota:** `POST /v1/charges` com `split`, autenticada com a chave de quem origina a venda. **Dica:** para a venda ficar vinculada a uma subconta, autentique com a chave da subconta. > [accordion] SPL-03 e SPL-04: validações do split > > Comprovam que o seu sistema trata a rejeição de um split inválido e interrompe a venda. Teste percentual `0`, percentual acima de `100`, soma acima de 100% e um `merchantId` que não existe ou não pertence ao grupo. > > **Rota:** `POST /v1/charges`. **Dica:** valide os percentuais no seu sistema antes de chamar a API, e mostre na evidência que o erro foi tratado. > [accordion] SPL-05: conferência do valor > > Este é o cenário que confirma se a comissão calculada é a que chega. Por padrão, a Finvia aplica o percentual sobre o **valor líquido**, depois da taxa transacional da cobrança. > > Enquanto houver parcelas a liquidar e nenhuma antecipação concluída, o `splitAmount` é uma simulação: mostra quanto o recebedor teria se o originador antecipasse, já descontada a taxa de antecipação estimada. Se a cobrança liquidar sem antecipação, o repasse é o percentual sobre o valor líquido, e a consulta passa a mostrar esse valor depois que as parcelas liquidam. Por isso, confira o `splitPercentage` e a coerência do `splitAmount` com a base de cálculo. Se a sua plataforma cobra comissão sobre o bruto, o percentual precisa ser ajustado. Exemplo: em uma venda de R\$ 100,00 no cartão 2x, com 5% de taxa transacional e R\$ 0,40 de taxa fixa, o líquido é R\$ 94,60, e uma comissão de 2% sobre o bruto (R\$ 2,00) exige `percentage` `2.1142`. A taxa de antecipação só entra na conta se o originador antecipar. > > **Rota:** `GET /v1/charges/{id}`. **Dica:** compare com o cálculo do seu sistema, usando as taxas de `GET /v1/fast-connect/sub-accounts/{id}/fees-info`. > [accordion] SPL-06: Pix e cartão parcelado > > As taxas de Pix e de cartão parcelado são diferentes, então o percentual calculado também muda. O cenário comprova que o split funciona nos dois métodos que você usa. > > **Rota:** `POST /v1/charges` e `GET /v1/charges/{id}` para cada método. ## C. Connect (subcontas) Cenários para quem usa o Connect para cadastrar e operar subcontas. Referências: [Connect](/guias/fast-connect/visao-geral) · [Criar subconta](/referencia/fast-connect/criar-subconta) · [Enviar documentos](/referencia/fast-connect/enviar-documentos) · [Chaves da subconta](/referencia/fast-connect/chaves-de-api) · [Criar saque](/referencia/fast-connect/criar-saque) · [Webhooks de conta](/guias/webhooks/conta) | Código | Cenário | Resultado esperado | Evidência a enviar | | - | - | - | - | | FC-01 | **Criar subconta** com todos os campos obrigatórios (dados da empresa, representante legal, conta bancária) | Subconta criada; retorna o `id`; status inicial de análise | Requisição + resposta + `id` | | FC-02 | **Enviar os documentos** da subconta (um por tipo: contrato social, cartão CNPJ, documento do responsável frente e verso, selfie com documento) | Cada envio retorna sucesso; a subconta passa a ter todos os documentos | Evidência de cada upload (tipo enviado + resposta) | | FC-03 | **Consultar a subconta** até a aprovação | Status evolui até `active`; credenciamento concluído | Resposta da consulta mostrando `active` | | FC-04 | **Obter as chaves de API** da subconta (quando ativa) | Retorna as chaves da subconta | Resposta (chaves podem vir mascaradas na evidência) | | FC-05 | **Criar uma cobrança na subconta** usando a chave dela | Cobrança `paid` vinculada à subconta | Requisição + resposta + `id` | | FC-06 | **Cobrança com split** entre subcontas do grupo | Split aplicado (ver seção B) | Referência ao cenário SPL correspondente | | FC-07 | **Saque da subconta** (valor em **reais**: `100` = R\$ 100,00) | Conferência de contrato: requisição montada com `amount` em reais e tratamento da resposta `{ "id" }` e dos erros documentados. Não executável com a chave de teste | Requisição montada pelo seu sistema + tratamento dos erros | | FC-08 | **Recebimento do aviso de status de conta** (mudança de status da subconta) | Aviso recebido e respondido com **`2xx`** | Print/log do aviso | ### Por que cada cenário existe e como executar > [accordion] FC-01: criar subconta > > Comprova que o cadastro envia todos os obrigatórios: `legalName`, `tradeName`, `companyTaxId`, `website`, `averageMonthlyRevenue`, `averageOrderValue`, `productType`, `legalRepresentative`, `contactEmail`, `productDescription`, `address`, `phones`, `bankAccount` e `canAccessDashboard` (com `user` quando `true`). > > **Rota:** `POST /v1/submerchants`, com a chave da conta master. **Dica:** guarde também os `id` de `legalRepresentatives` da resposta, usados no envio de documentos de sócios. > [accordion] FC-02: documentos > > Comprova que cada tipo de documento é enviado com o nome de campo certo (`social_contract`, `cnpj_card`, `responsible_document_front`, `responsible_document_back`, `selfie_with_document`), em formato aceito (JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF) e com até 50MB. > > **Rota:** `POST /v1/submerchants/{id}/document` em `multipart/form-data`, ou o fluxo com token (`POST /v1/submerchants/{merchantId}/document/upload-token` e `POST /v1/document-uploads`) para sócios adicionais. **Dica:** depois da aprovação, novos envios são bloqueados. > [accordion] FC-03 e FC-08: acompanhamento do status > > O FC-03 comprova que o seu sistema acompanha a subconta até `active`. O FC-08 comprova que o seu servidor recebe o aviso de mudança de status, que chega sem envelope, em camelCase (`merchantId`, `status`, `date` e, em `rejected` e `correcting`, `rejectionReason`). > > **Rota:** `GET /v1/submerchants/{id}`. O aviso vai para a `postbackUrl` informada em `POST /v1/submerchants`, que fica salva nas configurações da subconta. Sem ela, a subconta herda a URL de aviso da conta master, se houver. Para trocar a URL depois do cadastro, fale com o suporte. O aviso não vai aos endpoints de webhook do painel nem à `postbackUrl` das cobranças. **Dica:** só `pre_approved`, `correcting`, `active` (aprovação e desbloqueio), `rejected` e `blocked` geram aviso; `pending` e `inactive` não. Só uma resposta `2xx` conta como entregue. Deduplique por `merchantId` + `status` + `date`. > [accordion] FC-04 e FC-05: chaves e cobrança na subconta > > Comprovam que a venda fica vinculada à subconta certa. A cobrança precisa ser autenticada com a chave da própria subconta. > > **Rotas:** `GET /v1/submerchants/{id}/api-keys` e `POST /v1/charges`. **Dica:** use as chaves para cobrar só com a subconta `active`. Se a rota de chaves responder `404`, confira o `id` e o status da subconta. Em modo de teste, as chaves têm prefixo `sk_test_` e `pk_test_`. > [accordion] FC-06: split entre subcontas > > Repete os cenários da seção B no contexto do grupo Connect. Indique na evidência qual cenário SPL corresponde. > [accordion] FC-07: saque da subconta > > Comprova que o seu sistema pede o saque em reais e trata as respostas. O saque sai por Pix para a chave CNPJ da subconta, em `BRL`, com mínimo de R\$ 1,00, e sempre passa por aprovação manual. > > **Rota:** `POST /v1/submerchants/{merchantId}/payout-requests` com o corpo `{ "amount": 100 }`, autenticada com Basic e a `sk_` da conta master com Connect habilitado. A resposta de sucesso é `{ "id" }`. Com a chave de teste, a API responde `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`: não existe saque no sandbox. Por isso, este cenário é uma **conferência de contrato**: mostre a requisição que o seu sistema monta e como ele trata `422` (ex.: `SubMerchant account is not active`, `Insufficient balance. Required: X, Available: Y`) e o `400` de validação com `message` em lista. Se preferir, combine com o suporte um saque real de valor baixo em produção. **Dica:** a subconta precisa estar ativa, com CNPJ cadastrado como chave Pix e taxa de saque configurada. ## D. Apple Pay Cenários para quem oferece Apple Pay no checkout. Pré-requisito: o domínio ou os domínios onde o botão aparece devem estar **registrados e verificados** via API ([registrar domínio](/referencia/apple-pay/registrar-dominio), hospedar o arquivo de verificação, [validar domínio](/referencia/apple-pay/validar-dominio)), conforme o [guia de Apple Pay](/guias/cobrancas/apple-pay). As rotas de domínio usam a `sk_`; o registro vale para teste e produção ao mesmo tempo. Não é necessária conta Apple Developer nem certificados. A cobrança Apple Pay é enviada como cartão de crédito acompanhada do objeto de carteira (`wallet` com o token do Apple Pay), sempre em `BRL` e com `customer.document` presente. Referências: [Apple Pay](/guias/cobrancas/apple-pay) · [Listar domínios](/referencia/apple-pay/listar-dominios) · [Validar sessão](/referencia/apple-pay/validar-sessao) · [Criar cobrança](/referencia/cobrancas/criar) | Código | Cenário | Resultado esperado | Evidência a enviar | | - | - | - | - | | AP-01 | **Obter o token de pagamento** no front (Apple Pay JS / PassKit) | Token de pagamento gerado pelo dispositivo | Estrutura do token (pode ser redigida) | | AP-02 | **Cobrança Apple Pay aprovada** (cartão de crédito + `wallet` com o token) | Status `paid`; a cobrança é processada como cartão | Requisição (com `wallet`) + resposta + `id` | | AP-03 | **Domínio registrado e verificado** (`GET /v1/apple-pay/domains`) | Domínio com `status: "verified"`; sessão validada pelo `POST /v1/apple-pay/validate-merchant` sem erro | Resposta do GET mostrando `verified` | | AP-04 | **Tratamento de recusa** | Não aplicável no sandbox com o token da Apple, que sai aprovado. Comprove o tratamento da recusa com o cartão `4444333322221112` em uma cobrança de cartão comum | Requisição + resposta com `refused` (cobrança de cartão comum) | | AP-05 | **Estorno** de uma cobrança Apple Pay paga | Status `refunded`; webhook `charge.refunded` | Requisição de estorno + resposta + webhook | | AP-06 | **Recebimento do webhook** `charge.paid` | Evento recebido e respondido com **`2xx`** | Print/log do webhook | ### Por que cada cenário existe e como executar > [accordion] AP-01 e AP-03: token e domínio > > O AP-03 comprova a preparação: domínio registrado, arquivo hospedado em `/.well-known/apple-developer-merchantid-domain-association` (sem extensão, `text/plain`, sem redirecionamento) e domínio `verified`. O AP-01 comprova que o front-end valida a sessão com a chave pública e recebe o token no evento `onpaymentauthorized`. > > **Rotas:** `GET /v1/apple-pay/domains` (com a `sk_`) e `POST /v1/apple-pay/validate-merchant` (com a `pk_` ou a `pk_test_`, a partir do navegador). **Dica:** cada hostname é um registro próprio (`www.loja.com.br` e `loja.com.br` são domínios diferentes). Uma chave `pk_test_` valida a sessão no provedor real, mas a cobrança correspondente é simulada. > [accordion] AP-02 e AP-04: aprovação e recusa > > O AP-02 comprova que o backend envia o `payment.token` sem alterações em `paymentMethod.wallet.token`, com `installments` (de `1` a `12`), `currency` `BRL` e `customer.document`. No sandbox, a cobrança Apple Pay não tem um número de cartão controlável e sai aprovada; não há como forçar a recusa com o token da Apple. Por isso, o AP-04 aceita a recusa demonstrada com o cartão `4444333322221112` em uma cobrança de cartão comum, desde que o seu checkout use o mesmo tratamento de recusa para Apple Pay. > > **Rota:** `POST /v1/charges`, com a chave secreta. **Dica:** sem `customer.document`, a API responde `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED`; com outra moeda, `APPLE_PAY_CURRENCY_NOT_SUPPORTED`. > [accordion] AP-05 e AP-06: estorno e webhook > > Iguais aos cenários CHG-07 e CHG-08, aplicados a uma cobrança Apple Pay. ## E. Saques (payout) Cenários para quem faz o saque da **própria conta**. O saque de **subconta** (Connect) está no cenário FC-07. Referências: [Criar saque](/referencia/saques/criar) · [Listar saques](/referencia/saques/listar) · [Consultar saldo](/referencia/carteiras/listar) · [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento) > [!WARNING] > > **Saques não podem ser executados com a chave de teste.** `POST /v1/payout-requests` com `sk_test_` responde `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`, e a listagem com a chave de teste só traz registros de teste (na prática, vazia). Por isso, os cenários desta seção são uma **conferência de contrato**: você mostra a requisição que o seu sistema monta e como ele trata cada resposta documentada. A alternativa é combinar com o suporte um saque real de valor baixo em produção. Como funciona o saque da própria conta, para montar a conferência: | Item | Regra | | - | - | | Rota e autenticação | `POST /v1/payout-requests`, com Basic e a `sk_`. A chave precisa ser de um perfil com permissão de saque: chave de usuário Desenvolvedor recebe `403` com `Acesso negado` | | Corpo | `merchantId` (id da própria conta), `amount` (em reais, maior que zero, aceita decimais), `currency` `BRL` e `externalAccountDetails` `{ "type": "pix" }` | | Destino | Pix para a chave CNPJ da própria conta. Cadastre esse CNPJ como chave Pix em uma conta bancária da empresa antes de sacar. Não é possível escolher outra chave | | Resposta de sucesso | `201` **sem corpo**. Para obter o `id`, use `GET /v1/payout-requests` (do mais recente para o mais antigo) | | Status | `pending` (criado, valor reservado), `approved` (aprovado e enviado para pagamento) e `rejected` (recusado, valor volta ao saldo disponível) | | Limites | Valor máximo por saque configurado para a sua conta. Por padrão, um saque `pending` por moeda | | Taxa | A taxa de saque da conta é descontada: o valor transferido é `netAmount`. Na listagem, `amount` e `payoutFee` chegam como texto decimal (ex.: `"100.00000000"`) | | Webhook | Só os saques de subconta geram webhook, qualquer que seja a rota usada para criar. O saque da conta master ou de conta sem Connect não gera webhook: acompanhe pela listagem | | Código | Cenário | Resultado esperado | Evidência a enviar | | - | - | - | - | | PAY-01 | **Consultar o saldo** disponível antes do saque | `GET /v1/wallets` com `merchantId` devolve o saldo por moeda e `isWithdrawalEnabled` | Resposta da consulta de saldo (em produção) ou o trecho do código que a lê | | PAY-02 | Montar o **saque via Pix** (valor em **reais**) | Corpo com `merchantId`, `amount`, `currency` `BRL` e `externalAccountDetails.type` `pix`; `201` sem corpo tratado, com o `id` buscado na listagem | Requisição montada + tratamento do `201` | | PAY-03 | **Saldo insuficiente** | `422` com `Insufficient balance. Required: X, Available: Y` tratado | Trecho que trata o erro + mensagem exibida ao usuário | | PAY-04 | Saque **acima do limite** da conta | `422` com `Maximum withdrawal amount is X` tratado | Trecho que trata o erro | | PAY-05 | **Segundo saque com um já pendente** na mesma moeda | `422` com `You already have a pending withdrawal request for this currency` tratado | Trecho que trata o erro | | PAY-06 | **Acompanhar o status** do saque pela listagem | Status lidos de `GET /v1/payout-requests`: `pending`, `approved` ou `rejected` | Trecho que lê a listagem e trata os três status | | PAY-07 | **Valor em reais** (teste de sanidade) | O fluxo envia o valor em reais; um valor em centavos geraria um saque 100 vezes maior | Requisição mostrando o valor em reais | ### Por que cada cenário existe e como executar > [accordion] PAY-01: saldo antes do saque > > Comprova que o seu sistema consulta o saldo disponível antes de pedir o saque, evitando pedidos sem saldo. > > **Rota:** `GET /v1/wallets` com `merchantId` (obrigatório) e, opcionalmente, `currency`, autenticada com Basic e a `sk_`. A resposta é uma lista com `balance.available`, `balance.pending` e `balance.reserved` por moeda, e `isWithdrawalEnabled`. **Dica:** se `isWithdrawalEnabled` vier `false`, não ofereça o saque. > [accordion] PAY-02: saque por Pix > > Comprova que o pedido de saque é montado corretamente e que o `201` sem corpo é tratado. **Dica:** valor em reais, com casas decimais quando necessário (`100.50` = R\$ 100,50). Se a resposta for `422` com `Payout execution failed: ...` (acontece só em contas com aprovação automática), consulte a listagem antes de tentar de novo: o pedido pode ter ficado criado como `pending`. > [accordion] PAY-03, PAY-04 e PAY-05: regras de negócio > > Comprovam que o seu sistema trata as recusas por regra: saldo insuficiente, valor acima do limite máximo por saque configurado para a sua conta e saque pendente na mesma moeda. Todas chegam como `422`, com a mensagem em inglês. **Dica:** decida pelo código HTTP e mostre ao usuário um texto próprio. O PAY-05 não se reproduz em contas com Pix de aprovação automática nem em contas liberadas para mais de um saque pendente. > [accordion] PAY-06: acompanhamento > > Comprova que o seu sistema acompanha o saque pela listagem, já que o saque da própria conta não tem webhook. **Rota:** `GET /v1/payout-requests`, com `merchantId`, `status`, `currency`, `createdAtStart`, `createdAtEnd` (datas `AAAA-MM-DD`), `page` e `size`. Não envie `orderBy`. `approved` significa aprovado e enviado para pagamento: no Pix, a transferência do valor líquido sai no momento da aprovação. > [accordion] PAY-07: sanidade do valor > > Um teste deliberado para confirmar que o fluxo trabalha em reais. Mostre a requisição com o valor em reais e explique, na evidência, como o seu sistema converte o valor digitado pelo usuário. ## F. Cartão salvo e assinaturas Cenários para quem registra cartões ou cria assinaturas. > [!WARNING] > > **O que é simulado e o que é real neste bloco:** > > * O **cadastro do cartão** (`POST /v1/cards`) é real mesmo com a chave de teste: o cartão é guardado no cofre e registrado na adquirente, sem nenhuma cobrança. > * A **cobrança com cartão salvo** (`POST /v1/charges` com `cardTokenId`) é simulada no Modo Teste. > * As **assinaturas** cobram de verdade, inclusive a validação de R\$ 1,00 (com estorno) dos planos com trial grátis. > * O cofre é o mesmo para teste e produção: um `cardTokenId` criado na homologação cobra de verdade se for usado com a chave de produção. > > Para homologar assinaturas, use um **cartão real com valor baixo** e **cancele a assinatura no mesmo dia**: o cancelamento em até 7 dias da criação estorna automaticamente todas as cobranças pagas. Referências: [Assinaturas](/guias/assinaturas/visao-geral) · [Registrar cartão](/referencia/cartoes/registrar) · [Criar assinatura](/referencia/assinaturas/criar) · [Webhooks de assinatura](/guias/webhooks/assinatura) | Código | Cenário | Resultado esperado | Evidência a enviar | | - | - | - | - | | SUB-01 | **Registrar cartão** (`POST /v1/cards`, customer com e-mail e CPF/CNPJ) | Cartão criado com `status: "active"` e `pendingActivation: false` | Requisição (sem o PAN na evidência) + resposta + `id` | | SUB-02 | **Cobrança one-click com cartão salvo** (`POST /v1/charges` com `cardTokenId` + `cvv`) | Status `paid` (simulado no Modo Teste); comprovar que o CVV do comprador é coletado a cada cobrança | Requisição + resposta + `id` | | SUB-03 | **Criar plano** (`POST /v1/subscription-plans`, moeda `BRL`) | Retorna `{ "id": ... }` | Requisição + resposta | | SUB-04 | **Criar assinatura** (`POST /v1/subscriptions` com `cardTokenId` ou cartão inline) | Status `active`; primeira cobrança processada | Requisição + resposta + `id` | | SUB-05 | **Receber `subscription.created` e `subscription.activated`** | Eventos recebidos e respondidos com **`2xx`** | Print/log dos webhooks | | SUB-06 | **Cancelar dentro de 7 dias** (`POST /v1/subscriptions/{id}/cancel`) | `cancellationType: "regret"`, `refunded: true`; estorno das cobranças pagas conferido | Requisição + resposta + webhook `subscription.cancelled` | ### Por que cada cenário existe e como executar > [accordion] SUB-01 e SUB-02: cartão salvo > > O SUB-01 comprova que o cliente tem e-mail e CPF ou CNPJ (outros documentos são recusados) e que o cartão nasce `active`, sem etapa de ativação. Sem e-mail ou documento, a resposta é `400` com `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador`. O SUB-02 comprova que a recompra pede o CVV a cada cobrança: sem ele, a resposta é `400` com `CVV is required when using cardTokenId`. > > **Rotas:** `POST /v1/customers`, `POST /v1/cards` e `POST /v1/charges` com `cardTokenId`, `cvv` e `installments`. **Dica:** no Modo Teste, a cobrança do SUB-02 é simulada e segue as regras dos cartões de teste aplicadas ao número guardado. Como o cartão salvo costuma ser real, ela sai aprovada. > [accordion] SUB-03 e SUB-04: plano e assinatura > > Comprovam a criação do plano em `BRL` e da assinatura com primeira cobrança aprovada. Para homologar com custo mínimo, crie um plano de valor baixo e sem trial. > > **Rotas:** `POST /v1/subscription-plans` e `POST /v1/subscriptions`. **Dica:** se o plano tiver trial grátis, a Finvia cobra R\$ 1,00 para validar o cartão e estorna em seguida; essa validação não gera webhook. > [accordion] SUB-05: webhooks de assinatura > > Comprova que o endpoint recebe os eventos de assinatura, no envelope padrão com campos em snake\_case. > [accordion] SUB-06: cancelamento por arrependimento > > Comprova o cancelamento dentro de 7 dias, com estorno automático das cobranças pagas, e encerra o custo do teste. > > **Rota:** `POST /v1/subscriptions/{id}/cancel`, com `reason` opcional (até 500 caracteres). **Dica:** cancele no mesmo dia da criação. Anexe a resposta e o webhook `subscription.cancelled` com `cancellation_type` `regret`. ## Envio das evidências Não existe formulário de homologação. Ao final, fale com o suporte da Finvia para agendar a homologação e enviar as evidências, organizadas com **uma linha por cenário** deste roteiro (código, resultado e anexos). A equipe Finvia confere as evidências com você. > [!TIP] > > **Como saber que terminou:** todos os cenários das funcionalidades que você integrou têm evidência anexada e resultado igual ao esperado. Se a equipe Finvia apontar um cenário com problema, corrija a integração e envie a nova evidência antes da virada. ## Resumo por funcionalidade | Se você integrou | Execute | | - | - | | Cobrança Pix e cartão | CHG-01 a CHG-10 | | Split | SPL-01 a SPL-06 | | Subcontas Connect | FC-01 a FC-08 | | Apple Pay | AP-01 a AP-06 | | Saque da própria conta | PAY-01 a PAY-07 | | Cartão salvo e assinaturas | SUB-01 a SUB-06 | ## Veja também > [card] [Checklist de go-live](/homologacao/checklist-go-live) > > O que conferir na virada para produção. > [card] [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) > > Chave de teste, chave de produção e permissões. > [card] [Webhooks](/guias/webhooks/visao-geral) > > Canais, envelopes, entrega e idempotência. > [card] [Casos de uso](/casos-de-uso/visao-geral) > > Quais cenários cada modelo de negócio precisa. # Integrar com IA Source: https://docs.fastpaybrasil.com/integrar-com-ia Prompts prontos e atalhos para usar Claude Code, Codex, Gemini, Cursor, ChatGPT e outros assistentes na integração com a API da Finvia. Assistentes de programação como Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot fazem boa parte de uma integração quando recebem o contexto certo. Esta página reúne o que eles precisam: prompts prontos por tipo de integração e atalhos para entregar a documentação inteira ao assistente. > [!NOTE] > > O assistente escreve o código, mas a responsabilidade pela integração continua sendo do seu time. Revise o que ele produzir, rode os testes com a chave de teste e siga o [roteiro de homologação](/homologacao/roteiro) antes de ir para produção. ## Prompts prontos Clique em **Copy prompt** e cole no assistente que você usa, dentro do projeto que vai receber a integração. No Cursor, o botão **Open in Cursor** abre o prompt direto no editor. Cada prompt aponta para as páginas certas da documentação e já traz as regras que mais causam erro: autenticação, valores em reais, ausência de idempotência na criação de cobranças e tratamento de webhooks. ### Primeira cobrança Pix Cobrança Pix com QR Code, confirmação por webhook e tratamento de erros. Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md) * [https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md](https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/pix.md](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) * [https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md) * [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md) * [https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md) * [https://docs.fastpaybrasil.com/primeiros-passos/erros.md](https://docs.fastpaybrasil.com/primeiros-passos/erros.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar o pagamento por Pix no checkout. 1. Criar a cobrança Pix pelo servidor e devolver ao front-end o código copia e cola e o QR Code. 2. Receber o webhook de cobrança, atualizar o pedido e liberar a compra só quando o pagamento for confirmado. 3. Tratar Pix expirado e os erros de validação conforme a página de erros. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ### Cartão de crédito com 3D Secure Cartão parcelado, 3D Secure gerenciado e cartão salvo para recompra. Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) * [https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md) * [https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md) * [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) * [https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) * [https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md) * [https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar o pagamento com cartão de crédito. 1. Criar a cobrança com cartão, com parcelamento quando houver. 2. Tratar o status de autenticação 3D Secure gerenciado, levando o comprador ao endereço de autenticação e acompanhando o desfecho. 3. Oferecer o cartão salvo para a próxima compra, seguindo as regras do cofre de cartões. 4. Mostrar ao comprador uma mensagem clara em caso de recusa, sem expor detalhes técnicos. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ### Receptor de webhooks Endpoint que recebe, valida e processa os eventos da Finvia sem duplicar efeitos. Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md) * [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md) * [https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md) * [https://docs.fastpaybrasil.com/guias/webhooks/saque.md](https://docs.fastpaybrasil.com/guias/webhooks/saque.md) * [https://docs.fastpaybrasil.com/guias/webhooks/conta.md](https://docs.fastpaybrasil.com/guias/webhooks/conta.md) * [https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md) * [https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: criar o endpoint que recebe os webhooks da Finvia. 1. Responder rápido e processar o evento de forma assíncrona. 2. Registrar cada evento recebido e ignorar repetições, como explica a seção de idempotência no recebimento de webhooks. 3. Atualizar pedidos, assinaturas e saques conforme o catálogo de eventos. 4. Cadastrar o endpoint pela API, seguindo a referência de webhooks. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ### Assinaturas Planos, assinatura com trial, renovação automática, falhas e cancelamento. Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) * [https://docs.fastpaybrasil.com/guias/assinaturas/planos.md](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md) * [https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md) * [https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md) * [https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md) * [https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar a cobrança recorrente. 1. Criar os planos e a assinatura do cliente, com trial quando o plano tiver. 2. Liberar e bloquear o acesso do cliente de acordo com os eventos de assinatura. 3. Permitir troca de plano e cancelamento pelas rotas documentadas. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ### Subcontas, split e saques Marketplace ou plataforma com subcontas, divisão de pagamentos e saques por Pix. Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/split.md](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md) * [https://docs.fastpaybrasil.com/guias/fast-connect/saques.md](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md) * [https://docs.fastpaybrasil.com/guias/webhooks/conta.md](https://docs.fastpaybrasil.com/guias/webhooks/conta.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar o modelo de conta master com subcontas. 1. Cadastrar a subconta, enviar os documentos e acompanhar a análise pelos webhooks de conta. 2. Criar cobranças com split e conferir o valor de cada recebedor conforme a página de cálculo do split. 3. Solicitar saques por Pix da subconta e tratar o resultado. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ### Estorno, disputas e saldo Estorno total ou parcial, bloqueio cautelar, chargeback, MED e consulta de saldo. Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/guias/estorno.md](https://docs.fastpaybrasil.com/guias/estorno.md) * [https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) * [https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md) * [https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: implementar o pós-venda financeiro. 1. Permitir estorno pelo sistema de pedidos, respeitando as regras de prazo e de valor. 2. Tratar os eventos de bloqueio, chargeback e MED, avisando o time responsável. 3. Mostrar o saldo disponível, a liberar e reservado da conta. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ### Revisar uma integração e preparar a homologação Auditoria do código atual contra a documentação e o roteiro de homologação. Você vai integrar a API de pagamentos da Finvia neste projeto. Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa: * [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md) * [https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md](https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md) * [https://docs.fastpaybrasil.com/primeiros-passos/erros.md](https://docs.fastpaybrasil.com/primeiros-passos/erros.md) * [https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md) * [https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md) Regras que valem para toda a integração: * Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório. * Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento. * Valores em reais, não em centavos: `10` significa dez reais. * A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`. * O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo). * Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor. Tarefa: revisar a integração que já existe neste projeto. 1. Comparar cada chamada à API da Finvia com a documentação e apontar divergências de rota, campo, status ou tratamento de erro. 2. Conferir os itens do checklist de go-live e marcar o que falta. 3. Listar os testes do roteiro de homologação que o código ainda não cobre. Não altere o código antes de apresentar a lista de problemas encontrados. Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia. ## Atalhos em todas as páginas No topo de cada página da documentação há um menu com atalhos para assistentes de IA: | Atalho | O que faz | | - | - | | Copiar página | Copia a página em Markdown, pronta para colar no Claude Code, no Codex, no Gemini ou em qualquer outro assistente | | Ver como Markdown | Abre a versão em texto da página, que também pode ser enviada como link | | Abrir no ChatGPT, no Claude, no Gemini (AI Studio) ou no Perplexity | Abre o assistente já com a página como contexto, para você fazer perguntas sobre ela | | Conectar ao Cursor ou ao VS Code | Instala o servidor MCP da documentação no editor | Para levar uma página específica ao assistente, como a de [criar uma cobrança](/referencia/cobrancas/criar), use **Copiar página** e escreva o pedido logo abaixo do texto colado. ## Documentação inteira para o assistente Dois endereços entregam a documentação em formato próprio para IA: | Endereço | Conteúdo | | - | - | | [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) | Índice de todas as páginas, com links para a versão em Markdown de cada uma | | [https://docs.fastpaybrasil.com/llms-full.txt](https://docs.fastpaybrasil.com/llms-full.txt) | A documentação inteira num só arquivo de texto | Com o índice, o assistente encontra sozinho a página de que precisa. Basta incluir o endereço no pedido, como os prompts acima já fazem. ## Servidor MCP O servidor MCP deixa o assistente pesquisar a documentação da Finvia sempre que precisar, sem você copiar nada. O endereço é: ```text theme={null} https://docs.fastpaybrasil.com/mcp ``` No Claude Code, adicione com: ```bash theme={null} claude mcp add --transport http finvia-docs https://docs.fastpaybrasil.com/mcp ``` No Cursor e no VS Code, use o atalho **Conectar** do menu de cada página. Em outros assistentes, como Codex e Gemini CLI, adicione um servidor MCP remoto do tipo HTTP com o endereço acima, seguindo a documentação da ferramenta. ## Veja também > [card] [Sua primeira cobrança](/primeiros-passos/primeira-cobranca) > > O passo a passo da primeira chamada, para conferir o que o assistente fez. > [card] [Roteiro de homologação](/homologacao/roteiro) > > Os testes que a integração precisa passar antes de ir para produção. # Introdução Source: https://docs.fastpaybrasil.com/introducao O que a API da Finvia faz, para quem esta documentação foi escrita e por onde começar a leitura. A API da Finvia conecta o sistema da sua empresa à operação de pagamentos. Com ela você gera cobranças Pix e de cartão de crédito, guarda cartões para recompra, cobra assinaturas automaticamente, divide o valor de uma venda entre várias contas, solicita saques por Pix da própria conta e das subcontas e acompanha cada mudança por notificações enviadas ao seu servidor. Os meios de pagamento são dois: cartão de crédito (inclusive cartão salvo e Apple Pay) e Pix. Tudo acontece por requisições HTTPS com corpo em JSON, autenticadas com a chave secreta da sua conta. O mesmo endereço atende o ambiente de testes (sandbox) e o de produção: o que define o ambiente é a chave usada. O desenho abaixo mostra quem conversa com quem em uma integração típica, do pagamento do comprador ao aviso que chega ao seu servidor. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB C(["Comprador"]):::comprador FE["Seu front-end
site, checkout ou app"]:::lojista SV["Seu servidor
guarda a chave secreta sk_"]:::lojista API["Finvia API"]:::finvia ADQ["Adquirente e bandeiras
cartão e Apple Pay"]:::externo PIX["Sistema Pix
banco do comprador"]:::externo EV[["Webhooks e postbackUrl
charge.* · subscription.*
payout.*"]]:::evento BANK["Conta bancária
da sua empresa"]:::externo RX["Seu receptor de webhooks
HTTPS, responde 2xx"]:::lojista C -->|"1. escolhe e paga"| FE FE -->|"2. envia o pedido"| SV FE -.->|"Apple Pay e 3D Secure
com a chave pública pk_"| API SV -->|"3. HTTPS + JSON
Basic com a sk_"| API API -.->|"4. resposta
com o status"| SV API -->|"cartão"| ADQ API -->|"Pix"| PIX API -->|"5. avisa cada mudança"| EV API -->|"saque por Pix
para a chave CNPJ"| BANK EV -->|"6. POST no seu endereço"| RX classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 ``` A chave secreta (`sk_`) fica só no seu servidor. O front-end usa a chave pública (`pk_`) apenas no Apple Pay e no 3D Secure, e o saque sai sempre por Pix para a chave CNPJ da conta. ## Antes de começar Para integrar, sua empresa precisa de: * Conta ativa na Finvia e acesso ao [painel](https://app.finvia.com.br). * A chave de produção, criada automaticamente para o proprietário da conta, ou uma chave gerada por um usuário com perfil **Owner** ou **Manager** (veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave)). * Um servidor que receba requisições HTTPS da internet, para os webhooks. No desenvolvimento, uma ferramenta como o ngrok expõe sua máquina local. * Para o marketplace: o módulo Connect habilitado pela Finvia na sua conta. ## O que dá para fazer com a API | Necessidade do negócio | Recurso da API | Onde aprender | | - | - | - | | Receber por Pix, com QR Code ou código copia e cola | Cobrança Pix, com validade mínima de 15 minutos | [Pix](/guias/cobrancas/pix) | | Vender no cartão, à vista ou parcelado em até 12x | Cobrança com cartão de crédito | [Cartão de crédito](/guias/cobrancas/cartao-de-credito) | | Permitir recompra sem digitar o cartão de novo | Cartão salvo no cofre da Finvia (o comprador informa só o CVV) | [Cartão salvo](/guias/cobrancas/cartao-salvo) e [Cofre de cartões](/guias/cofre-de-cartoes) | | Aceitar a carteira digital da Apple no site | Apple Pay, com o token do dispositivo repassado ao processador | [Apple Pay](/guias/cobrancas/apple-pay) | | Autenticar o comprador junto ao banco emissor do cartão | 3D Secure em três formatos: gerenciado pela Finvia, pelo SDK ou pela API | [3D Secure](/guias/3d-secure/visao-geral) | | Cobrar o mesmo cliente todo mês, semana ou quinzena | Planos e assinaturas, com período de teste e retentativa automática | [Assinaturas](/guias/assinaturas/visao-geral) | | Operar como marketplace ou plataforma com vários vendedores | Connect: conta master, subcontas e divisão de valores (split) | [Connect](/guias/fast-connect/visao-geral) e [Split](/guias/fast-connect/split) | | Transferir o saldo para a conta bancária da empresa | Saque da própria conta, via Pix para a chave CNPJ da conta | [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento) e [Criar saque](/referencia/saques/criar) | | Transferir o saldo de um vendedor para a conta dele | Saque de subconta, via Pix para a chave CNPJ da subconta | [Saques](/guias/fast-connect/saques) | | Saber quando algo mudou sem ficar consultando a API | Webhooks de cobrança, assinatura, saque e conta | [Webhooks](/guias/webhooks/visao-geral) | | Consultar quanto há disponível, pendente e reservado | Saldos por moeda (carteiras) | [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento) | | Devolver o dinheiro ao cliente ou acompanhar uma disputa | Estorno total; bloqueio da cobrança em chargeback (cartão) ou MED, o Mecanismo Especial de Devolução do Pix | [Estorno](/guias/estorno) e [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) | > [!NOTE] > > **Para o negócio:** a API é a mesma para todos os modelos de venda. Uma loja virtual usa Pix, cartão e webhooks. Um SaaS soma planos e assinaturas. Um marketplace acrescenta o Connect, que cria uma subconta para cada vendedor e separa a parte de cada um em toda venda. Os [casos de uso](/casos-de-uso/visao-geral) mostram essas combinações com exemplos completos. ## Para quem é esta documentação Cada página foi escrita para ser lida por duas pessoas ao mesmo tempo. | Leitor | O que encontra aqui | | - | - | | **Desenvolvedor** | Qual rota chamar, o que enviar, o que volta, quais erros tratar e como testar no sandbox. Exemplos em cURL e Node.js prontos para adaptar. | | **Analista de negócios** | O que cada recurso resolve, quando usar, quais regras limitam o produto (prazos, valores mínimos, o que não é possível fazer) e o que pedir ao time técnico. | Ao longo das páginas, dois quadros ajudam a separar os assuntos: > [!NOTE] > > **Para o negócio:** decisões, regras comerciais e impactos para a operação. > [!TIP] > > **Para o desenvolvedor:** detalhes de implementação, armadilhas de código e formas de depurar. ## Como a documentação está organizada O portal tem cinco abas. Cada uma responde a uma pergunta diferente. | Aba | Pergunta que responde | O que tem dentro | | - | - | - | | **Documentação** | Como a API funciona? | Esta introdução, [conceitos](/conceitos), [mapa da API](/mapa-da-api), [glossário](/glossario), primeiros passos e anexos de consulta (status, eventos e erros) | | **Casos de uso** | Como o meu tipo de negócio usa a API? | Cenários completos por segmento, com arquitetura, passo a passo e checklist | | **Guias** | Como implemento um recurso específico? | Pix, cartão, 3D Secure, assinaturas, Connect, webhooks, estorno e saldos, com regras de negócio e exemplos | | **Referência da API** | Quais são os campos exatos de cada rota? | As 54 rotas, com parâmetros, respostas, códigos HTTP e exemplos | | **Homologação** | O que preciso comprovar antes de ir para produção? | Roteiro de cenários de teste e checklist de virada | ## Caminho recomendado de leitura > [tab] Desenvolvedor > > **1. Configure as credenciais** > > Gere a chave de teste e faça a primeira chamada autenticada em [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes). > > **2. Crie a primeira cobrança** > > Siga o tutorial [Sua primeira cobrança](/primeiros-passos/primeira-cobranca): Pix e cartão no sandbox, com recebimento de webhook. > > **3. Entenda os contratos gerais** > > Leia [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia) e [Erros e como tratar](/primeiros-passos/erros). Eles valem para todas as rotas. > > **4. Implemente os recursos do seu modelo** > > Abra o [caso de uso](/casos-de-uso/visao-geral) mais próximo do seu negócio e siga os guias que ele indica. > > **5. Consulte a referência e os anexos** > > Use a [Referência da API](/referencia/introducao) para os campos exatos e os anexos de [status](/anexos/status-de-cobranca), [eventos](/anexos/catalogo-de-eventos) e [códigos de erro](/anexos/codigos-de-erro) durante o desenvolvimento. > > **6. Homologue** > > Execute os cenários do [roteiro de homologação](/homologacao/roteiro), envie as evidências ao suporte da Finvia e confira o [checklist de go-live](/homologacao/checklist-go-live). > [tab] Analista de negócios > > **1. Aprenda o vocabulário** > > Leia [Conceitos essenciais](/conceitos) e deixe o [Glossário](/glossario) aberto para consulta. > > **2. Encontre o seu cenário** > > Escolha o [caso de uso](/casos-de-uso/visao-geral) mais parecido com a sua operação. Ele mostra quais recursos entram e quais regras precisam ser decididas. > > **3. Revise as regras que afetam o produto** > > Nos guias, leia as seções "Quando usar" e "Regras de negócio". Pontos que costumam virar decisão: validade do Pix, parcelamento, período de arrependimento das assinaturas, base de cálculo do split e taxa de saque. > > **4. Entenda o pós-venda** > > Veja [Status de cobrança](/anexos/status-de-cobranca) e [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) para definir quando liberar um pedido e como tratar disputas. > > **5. Acompanhe a homologação** > > Use o [roteiro de homologação](/homologacao/roteiro) para saber o que o time técnico deve comprovar antes da produção. A homologação é recomendada e acompanhada pela equipe Finvia, por meio do suporte. ## Primeiros passos > [card] [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) > > Gere suas chaves e faça a primeira chamada autenticada. > [card] [Sua primeira cobrança](/primeiros-passos/primeira-cobranca) > > Pix e cartão no sandbox, da criação ao webhook. > [card] [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia) > > Como listar dados e evitar cobranças duplicadas. > [card] [Erros e como tratar](/primeiros-passos/erros) > > Formatos de erro, códigos HTTP e boas práticas de retentativa. ## Casos de uso > [card] [E-commerce](/casos-de-uso/e-commerce) > > Loja virtual com Pix, cartão parcelado e produtos físicos. > [card] [SaaS e assinaturas](/casos-de-uso/saas-assinaturas) > > Planos recorrentes, período de teste e cancelamento. > [card] [Marketplace e PSP](/casos-de-uso/marketplace-psp) > > Subcontas por vendedor, split e saques com o Connect. > [card] [Infoprodutos](/casos-de-uso/infoprodutos) > > Cursos e produtos digitais, com divisão de valores entre parceiros. > [card] [ERP e software de gestão](/casos-de-uso/erp-software-de-gestao) > > Pagamentos embutidos no sistema que seus clientes já usam. > [card] [Cobrança por mensagem](/casos-de-uso/cobranca-por-link) > > Cobranças enviadas por mensagem, e-mail ou WhatsApp. > [card] [White label e agências](/casos-de-uso/white-label-agencias) > > Agências e plataformas que integram pagamentos para vários clientes. > [card] [Educação e mensalidades](/casos-de-uso/educacao-mensalidades) > > Mensalidades escolares e cursos com cobrança recorrente. ## Convenções que valem para toda a API | Tema | Regra | | - | - | | Endereço | `https://api-global.fastpaybrasil.com`, igual para sandbox e produção. O painel fica em `https://app.finvia.com.br` | | Autenticação | HTTP Basic com a chave secreta, inclusive em saldo e saques. Apple Pay (validação de sessão) e 3D Secure usam a chave pública, e o envio de documentos com token usa o token de upload (veja o [mapa da API](/mapa-da-api)) | | Valores | Em **reais**, com decimais: `10` significa R\$ 10,00 e `99.9` significa R\$ 99,90 | | Datas | Texto no padrão ISO 8601, como `2024-01-15T10:30:00.000Z` | | Identificadores | Texto, como `2vorkDcXyvzifL63YX09S9VqcnI` | | Nomes de campo | camelCase nas requisições e respostas da API. Os webhooks de cobrança e assinatura usam snake\_case no primeiro nível de `data` | | Meios de pagamento | Cartão de crédito (avulso, salvo e Apple Pay) e Pix | | Notificações | Webhooks cadastrados no painel e `postbackUrl` informada na cobrança | ## Veja também > [card] [Conceitos essenciais](/conceitos) > > Merchant, cobrança, webhook, split e outros termos explicados. > [card] [Mapa da API](/mapa-da-api) > > Todas as rotas em uma página, agrupadas por assunto. > [card] [Glossário](/glossario) > > Termos de pagamentos e da API em ordem alfabética. > [card] [Roteiro de homologação](/homologacao/roteiro) > > O que testar antes de ir para produção. # Mapa da API Source: https://docs.fastpaybrasil.com/mapa-da-api As 54 rotas da API da Finvia em uma página, agrupadas por assunto, com o que cada uma faz e como se autentica. Use esta página como índice. Cada tabela reúne as rotas de um assunto, explica em linguagem de negócio o que cada uma faz e mostra a autenticação usada. O link da última coluna leva à página de referência, com todos os campos, respostas e exemplos. Todas as rotas usam a mesma URL base, para sandbox e produção: ```text theme={null} https://api-global.fastpaybrasil.com ``` ## Como ler a coluna de autenticação | Valor na tabela | O que enviar no cabeçalho `Authorization` | | - | - | | **Basic, chave secreta** | `Basic` + Base64 de `sk_...:` (ou `sk_test_...:` no sandbox). É o padrão da API, inclusive em saldo, saques e endpoints de webhook | | **Basic, chave pública** | `Basic` + Base64 de `pk_...:` (ou `pk_test_...:`). Usada nas rotas chamadas pelo navegador: validação de sessão do Apple Pay e 3D Secure | | **Bearer, token de upload** | `Bearer` + token emitido por `POST /v1/submerchants/{merchantId}/document/upload-token`. Só no envio de documentos com token | A chave age com as permissões do usuário que a gerou. Uma chave de perfil sem permissão recebe `403` com `Acesso negado` (veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave)). Como montar o Basic: [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes). O desenho abaixo mostra de onde parte cada chamada e qual credencial ela usa. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart LR SV["Seu servidor"]:::lojista BR["Navegador ou app
do comprador"]:::lojista PK{{"Basic com a
chave pública pk_"}}:::finvia TK{{"Bearer com o
token de upload"}}:::finvia SK{{"Basic com a
chave secreta sk_"}}:::finvia R1["Apple Pay
validate-merchant"]:::evento R2["3D Secure
three-ds/* e resume-3ds"]:::evento R3["Envio de documentos
document-uploads"]:::evento R4["Demais rotas
cobranças, assinaturas,
Connect, saques e outras"]:::evento SV --> SK BR --> TK BR --> PK SK --> R4 TK --> R3 PK --> R1 PK --> R2 SK -.->|"upload-token emite
o token (300 s)"| TK classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 ``` ## Visão geral por grupo | Grupo | Rotas | Para que serve | | - | - | - | | Cobranças | 5 | Criar, listar, consultar, estornar e simular eventos de cobranças | | Apple Pay | 5 | Registrar e verificar domínios e validar a sessão de pagamento no navegador | | Saldos e meios de pagamento | 2 | Consultar saldo por moeda e meios de pagamento habilitados | | Saques | 2 | Sacar o saldo da própria conta por Pix e acompanhar os saques | | Clientes | 5 | Cadastro de quem paga | | Cartões | 4 | Cofre de cartões para recompra e assinaturas | | 3D Secure | 5 | Autenticação do comprador junto ao banco emissor | | Planos de assinatura | 7 | Modelos de cobrança recorrente | | Assinaturas | 5 | Vínculo de um cliente a um plano | | Connect | 10 | Subcontas, documentos, chaves, taxas e saques do marketplace | | Endpoints de webhook | 4 | Cadastrar, listar, alterar e excluir os endereços que recebem os webhooks | | **Total** | **54** | | O desenho abaixo organiza os grupos na ordem em que costumam aparecer em uma integração, da preparação da conta ao saque. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB subgraph S1["1. Preparar a conta"] PM["Meios de pagamento
testa a chave"]:::neutro WE["Webhooks
onde chegam os avisos"]:::neutro AP["Apple Pay
registra o domínio"]:::neutro FC["Connect
subcontas e documentos"]:::neutro end subgraph S2["2. Cadastrar quem paga"] CL["Clientes"]:::comprador CA["Cartões
cofre para recompra"]:::comprador end subgraph S3["3. Cobrar"] TD["3D Secure
autentica o comprador"]:::neutro CH["Cobranças
Pix e cartão"]:::finvia PL["Planos de assinatura"]:::neutro SU["Assinaturas
cobram a cada ciclo"]:::neutro end subgraph S4["4. Depois da venda"] RF["Cobranças
consulta e estorno"]:::neutro SA["Saldos e saques
Pix para a chave CNPJ"]:::neutro end CL --> CA CL --> CH CA --> SU CA -.->|"recompra"| CH PL --> SU TD --> CH SU -->|"gera"| CH CH --> RF CH --> SA S1 --> S2 style S1 fill:#F7F9FC,stroke:#D5DCE6 style S2 fill:#F7F9FC,stroke:#D5DCE6 style S3 fill:#F7F9FC,stroke:#D5DCE6 style S4 fill:#F7F9FC,stroke:#D5DCE6 classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` A ordem é uma sugestão. Os grupos que você vai usar dependem do seu modelo de negócio, como mostram os [casos de uso](/casos-de-uso/visao-geral). ## Cobranças | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `GET` | `/v1/charges` | Lista as cobranças, da mais recente para a mais antiga, com filtros por `status`, `currency`, período (`createdAtStart` e `createdAtEnd`) e busca (`searchFor`) | Basic, chave secreta | [Listar cobranças](/referencia/cobrancas/listar) | | `POST` | `/v1/charges` | Cria uma cobrança Pix, cartão, cartão salvo ou Apple Pay, com split opcional | Basic, chave secreta | [Criar uma cobrança](/referencia/cobrancas/criar) | | `GET` | `/v1/charges/{id}` | Consulta uma cobrança pelo `id`: status atual, valores, cliente, detalhes do pagamento e `splits` | Basic, chave secreta | [Consultar cobrança](/referencia/cobrancas/consultar) | | `POST` | `/v1/refunds` | Solicita o estorno total de uma cobrança paga | Basic, chave secreta | [Estornar cobrança](/referencia/cobrancas/estornar) | | `POST` | `/v1/charges/{id}/resend-webhook` | Gera um evento simulado, com o status escolhido, para uma cobrança de teste. Não altera a cobrança (só sandbox) | Basic, chave secreta | [Simular webhook de teste](/referencia/cobrancas/reenviar-webhook-teste) | > [!TIP] > > **Para o desenvolvedor:** `GET /v1/charges` não busca por `metadata` nem por identificador do seu pedido, e ignora `orderBy`. Guarde o `id` devolvido na criação junto com o seu pedido. Depois de um timeout, siga o [procedimento de timeout](/primeiros-passos/paginacao-ordenacao-idempotencia#procedimento-depois-de-um-timeout-ao-criar-cobrança). ## Apple Pay Rotas para preparar o Apple Pay na sua própria integração. Registrar o primeiro domínio ativa na conta o modelo em que a sessão é validada por `validate-merchant`. A cobrança em si usa a rota padrão `POST /v1/charges`. | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `POST` | `/v1/apple-pay/domains` | Registra o hostname onde o botão Apple Pay aparece e devolve o arquivo de verificação. Vale para teste e produção | Basic, chave secreta | [Registrar domínio](/referencia/apple-pay/registrar-dominio) | | `GET` | `/v1/apple-pay/domains` | Lista os domínios da conta e o status de cada um (`pending`, `verified` ou `failed`), sem paginação | Basic, chave secreta | [Listar domínios](/referencia/apple-pay/listar-dominios) | | `GET` | `/v1/apple-pay/domains/{id}` | Consulta um domínio, inclusive o arquivo de verificação | Basic, chave secreta | [Consultar domínio](/referencia/apple-pay/consultar-dominio) | | `POST` | `/v1/apple-pay/domains/{id}/validate` | Confere o arquivo hospedado e marca o domínio como `verified` | Basic, chave secreta | [Validar domínio](/referencia/apple-pay/validar-dominio) | | `POST` | `/v1/apple-pay/validate-merchant` | Valida a sessão Apple Pay no evento `onvalidatemerchant` do navegador | Basic, chave pública | [Validar sessão](/referencia/apple-pay/validar-sessao) | > [!NOTE] > > As rotas de domínio exigem que o usuário dono da chave tenha permissão de domínios Apple Pay (perfis Owner, Manager e Desenvolvedor). Em `validate-merchant`, a `pk_test_` também valida a sessão no provedor real, porque a janela de pagamento do Safari só abre com sessão real. ## Saldos e meios de pagamento | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `GET` | `/v1/wallets` | Mostra o saldo da conta por moeda: disponível, pendente e reservado, e se o saque está habilitado. Exige `merchantId` na consulta | Basic, chave secreta | [Listar carteiras](/referencia/carteiras/listar) | | `GET` | `/v1/payment-methods` | Lista os meios de pagamento habilitados para a conta, com filtro opcional por `currency` | Basic, chave secreta | [Listar meios de pagamento](/referencia/meios-de-pagamento/listar) | > [!TIP] > > **Para o desenvolvedor:** `GET /v1/payment-methods` é a forma mais simples de testar se a chave e o cabeçalho estão corretos. Resposta `200` significa autenticação válida. ## Saques | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `POST` | `/v1/payout-requests` | Solicita o saque do saldo da própria conta, por Pix para a chave CNPJ da conta. Responde `201` sem corpo | Basic, chave secreta | [Criar saque](/referencia/saques/criar) | | `GET` | `/v1/payout-requests` | Lista os saques, do mais recente para o mais antigo, com filtros por conta, status, moeda e período, e o total de pendentes (`pendingCount`) | Basic, chave secreta | [Listar saques](/referencia/saques/listar) | > [!WARNING] > > Não existe saque no Modo Teste: com a chave de teste, `POST /v1/payout-requests` responde `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. Uma chave de usuário Desenvolvedor recebe `403` com `Acesso negado` em saldo e saques. O acompanhamento de um saque é feito pela listagem. ## Clientes | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `GET` | `/v1/customers` | Lista clientes, com busca por nome, e-mail, documento ou telefone | Basic, chave secreta | [Listar clientes](/referencia/clientes/listar) | | `POST` | `/v1/customers` | Cadastra um cliente (`name`, `email`, `documentId` e `documentType` obrigatórios) | Basic, chave secreta | [Criar cliente](/referencia/clientes/criar) | | `GET` | `/v1/customers/{id}` | Consulta o cadastro de um cliente | Basic, chave secreta | [Consultar cliente](/referencia/clientes/consultar) | | `PUT` | `/v1/customers/{id}` | Atualiza nome, e-mail ou telefone. O documento não pode ser alterado | Basic, chave secreta | [Atualizar cliente](/referencia/clientes/atualizar) | | `DELETE` | `/v1/customers/{id}` | Remove o cliente (exclusão lógica). Responde `204` sem corpo | Basic, chave secreta | [Excluir cliente](/referencia/clientes/excluir) | ## Cartões | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `GET` | `/v1/cards` | Lista os cartões salvos, com filtro opcional por `customerId` | Basic, chave secreta | [Listar cartões](/referencia/cartoes/listar) | | `POST` | `/v1/cards` | Guarda um cartão no cofre e devolve o `id` usado em cobranças e assinaturas | Basic, chave secreta | [Registrar cartão](/referencia/cartoes/registrar) | | `GET` | `/v1/cards/{id}` | Consulta um cartão salvo: final, bandeira, validade e status | Basic, chave secreta | [Consultar cartão](/referencia/cartoes/consultar) | | `DELETE` | `/v1/cards/{id}` | Revoga o cartão no cofre. Ele não pode mais ser usado em cobranças nem assinaturas | Basic, chave secreta | [Excluir cartão](/referencia/cartoes/excluir) | O cartão já nasce `active` no cadastro, sem etapa de ativação. > [!WARNING] > > `POST /v1/cards` registra o cartão de verdade mesmo com a chave de teste (sem cobrar), e o cofre é o mesmo para teste e produção. A cobrança com cartão salvo (`POST /v1/charges` com `cardTokenId`) é simulada no Modo Teste. Veja [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes#o-que-é-simulado-no-modo-teste). ## 3D Secure | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `POST` | `/v1/three-ds/authenticate` | Inicia uma autenticação 3DS e pode devolver a URL de coleta de dados do navegador ou a URL do desafio | Basic, chave pública | [Iniciar autenticação](/referencia/3d-secure/iniciar) | | `POST` | `/v1/three-ds/submit` | Envia a autenticação depois da coleta de dados do navegador e informa se haverá desafio | Basic, chave pública | [Enviar autenticação](/referencia/3d-secure/enviar) | | `POST` | `/v1/three-ds/cancel` | Cancela uma autenticação em `requires_submission` ou `requires_challenge` | Basic, chave pública | [Cancelar autenticação](/referencia/3d-secure/cancelar) | | `POST` | `/v1/three-ds/challenge-result` | Obtém o resultado final do desafio, com o criptograma usado na cobrança | Basic, chave pública | [Resultado do desafio](/referencia/3d-secure/resultado-desafio) | | `POST` | `/v1/charges/{id}/resume-3ds` | Retoma uma cobrança em `authentication_required` depois do 3DS gerenciado. No fluxo gerenciado, quem chama é a própria página de autenticação | Basic, chave pública | [Retomar cobrança](/referencia/3d-secure/retomar-cobranca) | ## Planos de assinatura | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `GET` | `/v1/subscription-plans` | Lista os planos, com filtro por `merchantId` e `status` | Basic, chave secreta | [Listar planos](/referencia/planos/listar) | | `POST` | `/v1/subscription-plans` | Cria um plano com preço, moeda, periodicidade e período de teste opcional | Basic, chave secreta | [Criar plano](/referencia/planos/criar) | | `GET` | `/v1/subscription-plans/{id}` | Consulta um plano e o número de assinaturas ativas | Basic, chave secreta | [Consultar plano](/referencia/planos/consultar) | | `PUT` | `/v1/subscription-plans/{id}` | Atualiza um plano. A mudança vale só para novas assinaturas | Basic, chave secreta | [Atualizar plano](/referencia/planos/atualizar) | | `POST` | `/v1/subscription-plans/{id}/image` | Envia a imagem do plano (PNG, JPG ou JPEG) | Basic, chave secreta | [Enviar imagem do plano](/referencia/planos/enviar-imagem) | | `PATCH` | `/v1/subscription-plans/{id}/status` | Ativa um plano na hora ou pede a desativação, que sempre devolve um token de confirmação | Basic, chave secreta | [Alterar status do plano](/referencia/planos/alterar-status) | | `PATCH` | `/v1/subscription-plans/{id}/status/confirm` | Confirma a desativação com o token recebido (válido por 5 minutos) | Basic, chave secreta | [Confirmar desativação](/referencia/planos/confirmar-desativacao) | ## Assinaturas | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `GET` | `/v1/subscriptions` | Lista assinaturas, com filtro por merchant, cliente, status e busca por nome ou plano | Basic, chave secreta | [Listar assinaturas](/referencia/assinaturas/listar) | | `POST` | `/v1/subscriptions` | Cria a assinatura de um cliente em um plano, com cartão salvo ou cartão novo | Basic, chave secreta | [Criar assinatura](/referencia/assinaturas/criar) | | `GET` | `/v1/subscriptions/{id}` | Consulta a assinatura com o histórico de cobranças | Basic, chave secreta | [Consultar assinatura](/referencia/assinaturas/consultar) | | `PATCH` | `/v1/subscriptions/{id}` | Atualiza o `metadata` de uma assinatura ativa (único campo alterável) | Basic, chave secreta | [Atualizar assinatura](/referencia/assinaturas/atualizar) | | `POST` | `/v1/subscriptions/{id}/cancel` | Cancela a assinatura, com estorno automático em até 7 dias da criação | Basic, chave secreta | [Cancelar assinatura](/referencia/assinaturas/cancelar) | > [!NOTE] > > **Para o negócio:** as chaves geradas por usuários Desenvolvedor ou Financeiro recebem `403` em todas as rotas de planos e assinaturas, e a chave de Desenvolvedor também ao criar cobrança. O perfil Visualizador só acessa as consultas. Use uma chave de usuário Owner ou Manager. ## Connect Rotas do módulo de marketplace. Exigem o Connect habilitado pela Finvia na conta master. | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `GET` | `/v1/submerchants` | Lista as subcontas da conta master, com filtros por status, busca, período de criação e completude do cadastro | Basic, chave secreta | [Listar subcontas](/referencia/fast-connect/listar-subcontas) | | `POST` | `/v1/submerchants` | Cria uma subconta (vendedor) com dados da empresa, representante legal e conta bancária | Basic, chave secreta | [Criar subconta](/referencia/fast-connect/criar-subconta) | | `GET` | `/v1/submerchants/{id}` | Consulta uma subconta, com status e métricas de volume e split | Basic, chave secreta | [Consultar subconta](/referencia/fast-connect/consultar-subconta) | | `POST` | `/v1/submerchants/{id}/document` | Envia os documentos da subconta para análise. Documentos de pessoa vão para o representante legal | Basic, chave secreta | [Enviar documentos](/referencia/fast-connect/enviar-documentos) | | `POST` | `/v1/submerchants/{merchantId}/document/upload-token` | Emite um token de upload válido por 300 segundos, opcionalmente vinculado a um sócio | Basic, chave secreta | [Criar token de upload](/referencia/fast-connect/criar-token-upload) | | `POST` | `/v1/document-uploads` | Envia documentos usando o token de upload, inclusive direto do navegador, sem expor a chave | Bearer, token de upload | [Enviar documentos com token](/referencia/fast-connect/enviar-documentos-com-token) | | `GET` | `/v1/submerchants/{merchantId}/legal-representatives` | Lista os sócios da subconta e, com `include=documents`, os documentos de cada um | Basic, chave secreta | [Listar representantes](/referencia/fast-connect/listar-representantes) | | `GET` | `/v1/submerchants/{id}/api-keys` | Devolve as chaves pública e secreta da subconta ativa | Basic, chave secreta | [Chaves de API da subconta](/referencia/fast-connect/chaves-de-api) | | `GET` | `/v1/fast-connect/sub-accounts/{id}/fees-info` | Mostra as taxas efetivas da subconta (transacionais e de antecipação), a razão social e o CNPJ | Basic, chave secreta | [Taxas e dados da subconta](/referencia/fast-connect/taxas-e-dados) | | `POST` | `/v1/submerchants/{merchantId}/payout-requests` | Solicita o saque do saldo da subconta, via Pix para a chave CNPJ dela, sempre com aprovação manual | Basic, chave secreta | [Criar saque da subconta](/referencia/fast-connect/criar-saque) | Os saques das subcontas são acompanhados pela listagem [`GET /v1/payout-requests`](/referencia/saques/listar), que, para a conta master, traz também os saques das subcontas. Filtre por `merchantId` para ver uma conta só. ## Endpoints de webhook Rotas para cadastrar pela API os endereços que recebem os webhooks, inclusive os de uma subconta. O corpo usa snake\_case, e o `merchantId` da conta vai na query. | Método | Rota | O que faz | Autenticação | Referência | | - | - | - | - | - | | `POST` | `/v1/webhook-endpoints` | Cadastra um endpoint para a conta indicada em `merchantId`, com `url`, `enabled_events` e, na master com Connect, `include_submerchants`. Responde `201` sem corpo | Basic, chave secreta | [Criar endpoint](/referencia/webhooks/criar-endpoint) | | `GET` | `/v1/webhook-endpoints` | Lista os endpoints da conta indicada em `merchantId`, com busca e paginação | Basic, chave secreta | [Listar endpoints](/referencia/webhooks/listar-endpoints) | | `PUT` | `/v1/webhook-endpoints/{webhookId}` | Altera a URL, os eventos ou a opção de incluir subcontas | Basic, chave secreta | [Atualizar endpoint](/referencia/webhooks/atualizar-endpoint) | | `DELETE` | `/v1/webhook-endpoints/{webhookId}` | Exclui um endpoint | Basic, chave secreta | [Excluir endpoint](/referencia/webhooks/excluir-endpoint) | > [!NOTE] > > O endpoint cadastrado pelo painel (**Configurações > Webhooks**) recebe todos os eventos. O filtro por evento (`enabled_events`) só existe pela API; lista vazia significa todos. ## Veja também > [card] [Introdução à referência](/referencia/introducao) > > Convenções da referência da API. > [card] [Conceitos essenciais](/conceitos) > > O que é cada objeto que aparece nas rotas. > [card] [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia) > > Como funcionam as rotas de listagem. > [card] [Catálogo de códigos de erro](/anexos/codigos-de-erro) > > As mensagens de erro de cada rota. # Credenciais e ambientes Source: https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes Gere suas chaves, entenda a diferença entre testes e produção e faça a primeira chamada autenticada. Toda requisição à API da Finvia precisa de uma **chave secreta**. É com ela que a API sabe qual empresa está chamando, quais permissões ela tem e se a operação é de teste ou de produção. > [!NOTE] > > **Para o negócio:** a chave secreta dá acesso a cobranças, saldos e dados de clientes. Ela deve ficar só com o time técnico responsável pela integração, guardada no servidor, e nunca deve circular por e-mail, chat ou planilha. Se alguém de fora tiver acesso a ela, peça a troca ao suporte da Finvia imediatamente. ## Tipos de chave | Chave | Prefixo | Onde usar | Para que serve | | - | - | - | - | | Chave secreta de produção | `sk_` | Somente no servidor | Todas as operações reais: cobranças, assinaturas, saques | | Chave secreta de teste | `sk_test_` | Somente no servidor | Cobranças simuladas no ambiente de testes. Não faz saques | | Chave pública de produção | `pk_` | Navegador ou aplicativo | Fluxos que rodam no front-end, como Apple Pay e o SDK de 3D Secure | | Chave pública de teste | `pk_test_` | Navegador ou aplicativo | Os mesmos fluxos, no ambiente de testes | > [!WARNING] > > A chave **secreta** (`sk_`) nunca pode aparecer em código que roda no navegador, no aplicativo do cliente ou em repositórios. A chave **pública** (`pk_`) foi feita para o front-end e só é aceita nas rotas que pedem por ela. ### Onde a chave pública entra A chave pública vai no lugar do usuário do HTTP Basic, do mesmo jeito que a secreta, mas em chamadas feitas a partir do navegador: | Fluxo | Onde a `pk_` é usada | | - | - | | Apple Pay | Na validação da sessão (`POST /v1/apple-pay/validate-merchant`), chamada pelo front-end. Veja [Apple Pay](/guias/cobrancas/apple-pay) | | 3D Secure | Nas rotas de autenticação 3DS (`/v1/three-ds/*`), na retomada da cobrança (`POST /v1/charges/{id}/resume-3ds`) e na inicialização do SDK de segurança (`publicKey`). Veja [3D Secure](/guias/3d-secure/visao-geral) | | Subcontas do Connect | Cada subconta tem o próprio par `sk_`/`pk_`, que a conta master consulta em [Chaves de API da subconta](/referencia/fast-connect/chaves-de-api) | A chave pública não cria cobranças. Ela pode ficar no HTML da página ou no aplicativo, porque só é aceita nesses fluxos. A conta precisa estar ativa para a `pk_` funcionar. ## Ambientes de teste e produção A Finvia usa o **mesmo endereço** para testes (sandbox) e produção. O ambiente é definido pela chave enviada na requisição: com a chave de teste (Modo Teste), as cobranças são simuladas; com a chave de produção, as transações são reais. | Ambiente | URL base | Quando usar | | - | - | - | | Produção | `https://api-global.fastpaybrasil.com` | Transações reais com clientes reais | | Sandbox | `https://api-global.fastpaybrasil.com` | Desenvolvimento e homologação, com a chave de teste | Os outros endereços que você vai usar: | Para quê | Endereço | | - | - | | Painel | `https://app.finvia.com.br` | | Site | `https://www.finvia.com.br` | | Documentação | `https://docs.fastpaybrasil.com` | | SDK de 3D Secure via CDN | `https://js.fastpaybrasil.com/security-sdk.min.js` | A sua aplicação precisa de uma única variável de configuração para a URL e de uma variável para a chave. Trocar de ambiente é trocar a chave. ```bash theme={null} export FINVIA_API_URL="https://api-global.fastpaybrasil.com" export FINVIA_API_KEY="sua_chave_secreta" ``` A chave pública de teste (`pk_test_`) também coloca as chamadas do front-end em modo de teste. A exceção é a validação de sessão do Apple Pay: ela sempre vai ao provedor real, porque a janela de pagamento do Safari só abre com uma sessão real. A cobrança Apple Pay criada depois, com a chave de teste, é simulada normalmente. ### O que é simulado no Modo Teste O desenho abaixo mostra como a chave define o ambiente e quais operações continuam reais mesmo com a chave de teste. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB R(["Requisição à API
mesma URL nos dois"]):::neutro Q{"Qual chave
foi enviada?"}:::decisao TEST["Modo Teste
sk_test_"]:::alerta PROD["Produção
sk_"]:::finvia T1["Cobranças
simuladas, inclusive com
cartão salvo e Apple Pay"]:::ok T2["Cadastro de cartão
registro real no cofre,
sem cobrança"]:::alerta T3["Assinaturas
cobram de verdade,
inclusive o R$ 1,00 do trial"]:::erro T4["Saques
recusados com 403"]:::erro REAL["Todas as operações
são reais"]:::ok R --> Q Q -->|"sk_test_"| TEST Q -->|"sk_"| PROD TEST --> T1 TEST --> T2 TEST --> T3 TEST --> T4 PROD --> REAL T2 -.->|"mesmo cofre:
o cardTokenId cobra
de verdade com sk_"| PROD classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` > [!WARNING] > > **Toda cobrança via `POST /v1/charges` é simulada no Modo Teste, inclusive com cartão salvo (`cardTokenId`) e Apple Pay.** Duas operações, porém, não têm modo de teste: > > * **Cadastro de cartão (`POST /v1/cards`):** registra o cartão de verdade no cofre e na adquirente, mas não cobra nada. > * **Assinaturas (`POST /v1/subscriptions`):** as cobranças da assinatura são feitas de verdade, inclusive a validação de R\$ 1,00 (com estorno em seguida) dos planos com trial grátis. > > O cofre de cartões é o mesmo para teste e produção. Um `cardTokenId` criado durante os testes também funciona com a chave de produção, e aí a mesma chamada cobra de verdade. Para homologar assinaturas, use um cartão real com valor baixo e cancele a assinatura no mesmo dia. O cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas. ### Cartões de teste No Modo Teste, o resultado da cobrança de cartão depende só do número. Envie o número só com dígitos, sem espaços (com espaços, a API responde `400`). | Número | Resultado | `status` / `reason` | | - | - | - | | `4444333322221111` | Aprovado | `paid` / `success` | | `4444333322221112` | Recusado | `refused` / `card_declined` | | Qualquer número terminado em `2222` (ex.: `4444333322222222`) | Pendente | `pending` / `pending`. A cobrança fica pendente e não há confirmação posterior simulada | | Qualquer outro número | Aprovado | `paid` / `success` | Nome, CVV e validade não mudam o resultado. Use qualquer nome, CVV numérico de 3 dígitos e validade futura (mês com 2 dígitos, ex.: `05`, e ano com 4). O parcelamento de 1 a 12 vezes funciona igual, desde que a conta tenha taxa configurada para o número de parcelas. > [!NOTE] > > Esses números só valem com a chave de teste. As regras de 3D Secure e de antifraude da conta continuam valendo no Modo Teste: se a conta exige 3DS ou tem antifraude ligado, a recusa pode vir dessas etapas, com `reason` começando em `3ds_` ou igual a `antifraud_denied`. Na cobrança com cartão salvo, a regra vale para o número guardado; como esse cartão costuma ser real, a cobrança de teste sai aprovada. ## Onde obter as chaves As chaves ficam no [painel da Finvia](https://app.finvia.com.br), em **Configurações > Chave de API**. A página se chama **Chaves de API** e tem duas abas: **Produção** e **Teste**. Não existe rota de API para a conta ler as próprias chaves. **Em validação (V-56):** os rótulos do painel citados nesta seção estão sendo conferidos na versão em produção. Se algum nome estiver diferente, procure a página de chaves em **Configurações**. O desenho abaixo resume o caminho da conta aprovada até as chaves de teste e de produção. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB A(["Conta cadastrada
e aprovada"]):::neutro AUTO["Par sk_ / pk_ de produção
criado automaticamente
pertence ao proprietário"]:::finvia P["Painel: Configurações >
Chave de API (V-56)"]:::lojista Q{"Qual aba?"}:::decisao GT["Gerar chave de teste
e confirmar em Criar chave"]:::lojista TPAIR["Par sk_test_ / pk_test_"]:::alerta GP["Se ainda não existir:
Gerar chave de produção"]:::lojista REV["Revelar chave
código no e-mail, vale 5 min"]:::lojista SK["Chave secreta
só no servidor"]:::ok PK["Chave pública
no front-end"]:::ok A --> AUTO A -->|"usuário Owner ou Manager"| P P --> Q Q -->|"Teste"| GT GT --> TPAIR Q -->|"Produção"| GP AUTO -.-> GP TPAIR --> REV GP --> REV REV --> SK REV --> PK classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` Os nomes do painel usados no desenho seguem a mesma ressalva de validação (V-56) do quadro acima. > [tab] Chave de produção > > **1. Abra a aba Produção** > > Em **Configurações > Chave de API**, abra a aba **Produção**. O par `sk_`/`pk_` de produção é criado automaticamente no cadastro ou na aprovação da conta e pertence ao proprietário dela. Se ele ainda não existir, a aba mostra o botão **Gerar chave de produção**. > > **2. Revele a chave** > > Clique em **Revelar chave**. Um código de verificação é enviado ao seu e-mail e vale 5 minutos. > > **3. Copie o par** > > Depois de informar o código, o painel mostra juntas a **Chave secreta** (`sk_`) e a **Chave pública** (`pk_`). Guarde a secreta em um cofre de segredos ou na variável de ambiente do servidor. > [tab] Chave de teste > > **1. Abra a aba Teste** > > Em **Configurações > Chave de API**, abra a aba **Teste**. > > **2. Gere o par de teste** > > Clique em **Gerar chave de teste** e confirme em **Criar nova chave de API?** > **Criar chave**. O sistema gera o par `sk_test_`/`pk_test_`. > > **3. Revele a chave** > > Clique em **Revelar chave**, informe o código enviado ao seu e-mail (válido por 5 minutos) e copie a **Chave secreta** (`sk_test_`) e a **Chave pública** (`pk_test_`). No painel, os perfis Owner, Manager e Desenvolvedor podem gerar e revelar chaves. O perfil Visualizador só vê a página. Para a integração, gere as chaves, inclusive a de teste, com um usuário **Owner** ou **Manager**: uma chave gerada por Desenvolvedor fica com as restrições desse perfil (veja [Permissões da chave](#permissões-da-chave)). A `sk_` e a `pk_` formam um par. Se a chave secreta for trocada (a troca é feita pelo suporte), a chave pública também muda e precisa ser atualizada no front-end. Cada par pertence a uma única conta. Formato de uma chave: ```text theme={null} sk_9a8s7d6f5g4h3j2k1l0z9x8c7v6b5n4m3 ``` ### Permissões da chave A chave **age com as permissões do usuário que a gerou**. Quem apenas revela a chave no painel não muda essas permissões. A chave de produção criada automaticamente pertence ao proprietário da conta e funciona em todas as rotas. Uma chave gerada por outro usuário fica limitada ao perfil dele, e isso vale também para a chave de teste. | Perfil do usuário que gerou a chave | O que a chave consegue fazer | | - | - | | Owner, Manager e Operador | Cobranças, planos e assinaturas | | Visualizador | Só as consultas (`GET`) de planos e assinaturas. As demais rotas de planos e assinaturas respondem `403` | | Desenvolvedor | Não cria cobranças nem acessa planos e assinaturas. Também recebe `403` em saldo (`GET /v1/wallets`) e em saques (`/v1/payout-requests`) | | Financeiro | Recebe `403` em todas as rotas de planos e assinaturas | | Perfil personalizado | Depende das permissões marcadas no perfil | Quando falta permissão, a resposta é: ```json theme={null} { "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 } ``` > [!TIP] > > **Para o desenvolvedor:** gere a chave de teste com um usuário Owner ou Manager. Se ela for gerada por um usuário Desenvolvedor, os testes de cobrança falham com `403`. Quando a integração consulta dados mas recebe `403` ao criar cobranças, confira primeiro o perfil de quem gerou a chave. ## Como se autenticar A API usa **HTTP Basic Auth**. A chave secreta vai no lugar do usuário e a senha fica vazia. Passo a passo: **1. Pegue a chave** `sk_abc123` **2. Acrescente dois pontos no final** `sk_abc123:` (os dois pontos separam usuário e senha; como a senha é vazia, não há nada depois deles) **3. Converta para Base64** `c2tfYWJjMTIzOg==` **4. Envie no cabeçalho de toda requisição** `Authorization: Basic c2tfYWJjMTIzOg==` > [!TIP] > > **Para o desenvolvedor:** para conferir se o Base64 foi montado certo, decodifique o valor e veja se ele termina com `:`. Se os dois pontos estiverem faltando, a API responde `401`. ### Teste a conexão A forma mais simples de validar a chave é listar os meios de pagamento disponíveis para a sua conta. Resposta `200` significa que a autenticação está correta. ```http REST (JSON) theme={null} GET /v1/payment-methods HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/payment-methods" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} // conexao.mjs (Node.js 18+, ESM, await no topo) const API_URL = 'https://api-global.fastpaybrasil.com'; const apiKey = process.env.FINVIA_API_KEY; const credentials = Buffer.from(`${apiKey}:`).toString('base64'); const response = await fetch(`${API_URL}/v1/payment-methods`, { headers: { Authorization: `Basic ${credentials}` }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 'https://api-global.fastpaybrasil.com/v1/payment-methods', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Basic ' . $credentials, 'Content-Type: application/json' ] ]); $response = curl_exec($curl); curl_close($curl); ``` ```python Python theme={null} import os import base64 import requests api_key = os.environ['FINVIA_API_KEY'] credentials = base64.b64encode(f'{api_key}:'.encode()).decode() response = requests.get( 'https://api-global.fastpaybrasil.com/v1/payment-methods', headers={ 'Authorization': f'Basic {credentials}', 'Content-Type': 'application/json', }, ) ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payment-methods")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/payment-methods"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/payment-methods", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/payment-methods") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ## Boas práticas de segurança * Guarde a chave em variável de ambiente ou cofre de segredos, nunca no código-fonte. * Use chaves diferentes para cada ambiente e nunca reaproveite a chave de produção em testes. * Use sempre HTTPS. * Se houver suspeita de vazamento da chave secreta, peça a troca ao suporte imediatamente. Depois da troca, atualize a `sk_` no servidor e a `pk_` no front-end, porque as duas mudam juntas. * Acompanhe os logs de acesso da sua aplicação para identificar uso fora do padrão. ```javascript theme={null} // Evite: chave no código // const apiKey = 'sk_9a8s7d6f5g4h3j2k1l0z9x8c7v6b5n4m3'; // Faça: chave em variável de ambiente const apiKey = process.env.FINVIA_API_KEY; console.log(apiKey ? 'Chave carregada do ambiente' : 'Defina FINVIA_API_KEY'); ``` ## Erros comuns | Código | Resposta | Causa | Como resolver | | - | - | - | - | | `401` | `{"statusCode": 401, "message": "Unauthorized"}` | Chave inválida, cabeçalho ausente ou formato incorreto | Confira os dois pontos antes do Base64, o prefixo `Basic ` e se a chave é do ambiente certo | | `403` | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | O perfil do usuário que gerou a chave não tem permissão para a rota | Gere a chave com um usuário Owner ou Manager | | `403` | `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Pedido de saque com a chave de teste. Não existe saque no Modo Teste | Teste saques só em produção, com valor baixo | ## Perguntas frequentes > [accordion] Preciso mudar a URL para sair do sandbox? > > Não. A URL é a mesma. Para ir para produção, troque a chave de teste (`sk_test_`) pela chave de produção (`sk_`). > [accordion] Perdi a chave. Consigo ver de novo? > > Sim. Em **Configurações > Chave de API**, clique em **Revelar chave** e informe o código enviado ao seu e-mail. > [accordion] Posso testar assinaturas com a chave de teste? > > As assinaturas cobram de verdade mesmo com a chave de teste, e o cadastro de cartão registra o cartão de verdade (sem cobrar). Use um cartão real com valor baixo e cancele a assinatura no mesmo dia: o cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas. > [accordion] Uma cobrança com cartão salvo cobra de verdade no Modo Teste? > > Não. Com a chave de teste, toda cobrança em `POST /v1/charges` é simulada, inclusive com `cardTokenId`. O `cvv` continua obrigatório. Lembre que o mesmo `cardTokenId` cobra de verdade se for usado com a chave de produção. > [accordion] Quem da minha empresa deve gerar a chave? > > Um usuário com perfil Owner ou Manager. Uma chave gerada por Desenvolvedor não cria cobranças nem assinaturas e não acessa saldo nem saques. > [accordion] Os webhooks de teste vão para endpoints separados? > > Não. A lista de endpoints de webhook é uma só e recebe eventos de teste e de produção. Nos eventos de cobrança de teste, `livemode` vem `false` e `data.is_test` vem `true`. Veja [Sua primeira cobrança](/primeiros-passos/primeira-cobranca). ## Veja também > [card] [Sua primeira cobrança](/primeiros-passos/primeira-cobranca) > > Crie e acompanhe uma cobrança Pix no sandbox. > [card] [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia) > > Como listar dados e evitar cobranças duplicadas. > [card] [Erros e como tratar](/primeiros-passos/erros) > > Códigos HTTP e respostas de erro da API. > [card] [Roteiro de homologação](/homologacao/roteiro) > > O que testar antes de ir para produção. # Erros e como tratar Source: https://docs.fastpaybrasil.com/primeiros-passos/erros Formato das respostas de erro, o que cada código HTTP significa na API da Finvia e como decidir entre corrigir, consultar ou tentar de novo. Quando uma requisição não dá certo, a API responde com um código HTTP e um corpo JSON que explica o motivo. Esta página mostra como ler esse corpo, o que cada código significa e qual reação o seu sistema deve ter. A lista completa de mensagens por rota está no [Catálogo de códigos de erro](/anexos/codigos-de-erro). > [!NOTE] > > **Para o negócio:** um bom tratamento de erros evita dois problemas para a operação: cobrar o cliente duas vezes (por repetir uma requisição que já tinha funcionado) e perder uma venda (por não mostrar ao cliente uma alternativa quando o cartão é recusado). Os dois casos estão cobertos abaixo. ## Formato da resposta de erro A API usa três formatos de corpo de erro. O formato depende da rota e do tipo de erro, então o seu código precisa aceitar os três. **1. Formato padrão**, com `statusCode`, `message` e `error`. É o da maior parte das rotas: ```json theme={null} { "statusCode": 404, "message": "Cobrança não encontrada", "error": "Not Found" } ``` Nos erros de validação do corpo (campo ausente, tipo errado, valor fora do limite), o código é `400` e `message` vem como **lista** de textos, um por problema: ```json theme={null} { "statusCode": 400, "message": [ "shippingAddress.country must be a valid ISO31661 Alpha3 code" ], "error": "Bad Request" } ``` O `401` vem só com `statusCode` e `message`: `{ "statusCode": 401, "message": "Unauthorized" }`. | Campo | Tipo | O que contém | | - | - | - | | `statusCode` | integer | O mesmo código HTTP da resposta | | `message` | string ou lista de strings | Descrição do problema. Em validação de campos, uma lista | | `error` | string | Nome padrão do código HTTP (ex.: `Bad Request`, `Forbidden`, `Not Found`). Nem toda resposta traz | **2. Formato com código de negócio**, com `code` e `message`, sem `statusCode`. Aparece nos erros de negócio do Apple Pay e na validação de cartão da criação de assinatura: ```json theme={null} { "code": "CARD_VALIDATION_FAILED", "message": "Não foi possível validar o cartão: cobrança recusada." } ``` | Onde | Códigos | | - | - | | Apple Pay (`/v1/apple-pay/*` e cobrança com Apple Pay) | `APPLE_PAY_INVALID_DOMAIN`, `APPLE_PAY_DOMAIN_NOT_VERIFIED`, `APPLE_PAY_RATE_LIMITED` e os demais listados no [catálogo](/anexos/codigos-de-erro) | | Validação do cartão em `POST /v1/subscriptions` (plano com trial grátis) | `CARD_VALIDATION_FAILED` (`422`), `CARD_VALIDATION_IN_PROGRESS` (`409`), `CARD_VALIDATION_RATE_LIMITED` (`429`) | Nessas mesmas rotas, os erros de validação de campo e de permissão continuam no formato padrão. **3. Formato do envio de documentos com token**, com `error`, `message` e `details`, sem `statusCode`. Aparece nos erros de arquivo de `POST /v1/document-uploads`: ```json theme={null} { "error": "FILE_TOO_LARGE", "message": "O arquivo excede o tamanho máximo de 50 MB.", "details": { "maxMb": 50, "actualMb": 62.4 } } ``` Nessa rota, os erros do token (`401` e `403`) voltam ao formato padrão. > [!TIP] > > **Para o desenvolvedor:** decida o fluxo pelo código HTTP e, quando existir, pelo campo `code` (formato 2) ou `error` (formato 3). Use o `message` só para log e suporte. As mensagens misturam português e inglês (`Cobrança não encontrada`, `Insufficient balance. Required: X, Available: Y`) e podem mudar. Não faça comparação exata de texto para decidir regra de negócio. ```javascript Node.js theme={null} // Lê os três formatos de erro e devolve um objeto único function lerErro(status, corpo) { const mensagens = Array.isArray(corpo?.message) ? corpo.message : [corpo?.message].filter(Boolean); return { status, // decida por aqui codigo: corpo?.code ?? (corpo?.statusCode ? undefined : corpo?.error), // formatos 2 e 3 mensagens, // só para log detalhes: corpo?.details, }; } console.log(lerErro(400, { statusCode: 400, message: ['amount must not be less than 1'], error: 'Bad Request' })); console.log(lerErro(422, { code: 'CARD_VALIDATION_FAILED', message: 'Não foi possível validar o cartão: cobrança recusada.' })); ``` ### Erro de permissão por perfil A chave age com as permissões do usuário que a gerou. Quando o perfil desse usuário não tem permissão para a rota, a resposta é `403`: ```json theme={null} { "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 } ``` Isso acontece, por exemplo, com chave gerada por usuário Desenvolvedor ao criar cobrança, em saldo e em saques, e com chave de Desenvolvedor ou Financeiro nas rotas de planos e assinaturas. Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave). ### Resultados que não são erro HTTP | Situação | Como aparece | | - | - | | Recusa de cartão | A cobrança é criada (`201`) com `status` `refused` ou `failed` e o motivo em `reason`. Também sai o webhook `charge.refused` ou `charge.failed` | | 3D Secure obrigatório e não feito | A cobrança volta com `status` `refused` e `reason` com o código no início, como `3ds_required: ...` | | Consulta de cobrança com `id` inexistente | `GET /v1/charges/{id}` responde hoje `200` com corpo vazio. Trate corpo vazio como "não encontrada" | ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "refused", "paymentDetails": null, "reason": "3ds_required: Não foi possível completar a autenticação 3DS obrigatória" } ``` ## Códigos HTTP usados pela API ### Sucesso | Código | Significado | Onde aparece | | - | - | - | | `200` | Requisição atendida | Consultas, listagens, atualizações, ações de 3DS, cancelamento de assinatura, validação de domínio Apple Pay, atualização e exclusão de endpoint de webhook (sem corpo) | | `201` | Recurso criado | Cobrança, estorno, cliente, cartão, plano, assinatura, subconta, token de upload, documentos, domínio Apple Pay, simulação de webhook de teste e saque. Em `POST /v1/payout-requests` e `POST /v1/webhook-endpoints`, o `201` vem **sem corpo**: o `id` se obtém na listagem | | `204` | Atendida, sem corpo na resposta | `DELETE /v1/customers/{id}`, `POST /v1/subscription-plans/{id}/image` e `PATCH /v1/subscription-plans/{id}/status/confirm` | > [!WARNING] > > `201` na criação de uma cobrança **não** significa pagamento aprovado. Leia o campo `status`: no cartão, ele pode vir `refused` ou `failed`. No Pix, vem `pending` até o cliente pagar. ### Erros do cliente (4xx) O desenho abaixo resume a primeira coisa a conferir em cada código 4xx. Os exemplos de mensagem estão na tabela. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart LR Q{"Erro 4xx
recebido"}:::decisao C400["400"]:::erro C401["401"]:::erro C403["403"]:::erro C404["404"]:::erro C409["409"]:::erro C413["413 · 415"]:::erro C422["422"]:::erro C429["429"]:::alerta A400["Corrija o corpo: message
pode vir como lista"]:::neutro A401["Confira a chave, o Basic
e os dois pontos no fim"]:::neutro A403["Confira o perfil de quem
gerou a chave e o Connect"]:::neutro A404["Confira o id e se ele
pertence à conta da chave"]:::neutro A409["CNPJ: consulte o cadastro
Apple Pay: repita a chamada
Cartão: espere a validação"]:::neutro A413["Envie PDF ou imagem
de até 50 MB"]:::neutro A422["Leia o motivo e corrija
a regra de negócio"]:::neutro A429["Aguarde. Não repita
em laço"]:::neutro Q --> C400 --> A400 Q --> C401 --> A401 Q --> C403 --> A403 Q --> C404 --> A404 Q --> C409 --> A409 Q --> C413 --> A413 Q --> C422 --> A422 Q --> C429 --> A429 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 ``` | Código | Significado | Exemplos reais | O que fazer | | - | - | - | - | | `400` | Corpo inválido ou operação não permitida no estado atual | Lista em `message` (validação), `Shipping info must be provided for merchants selling physical items.`, `CVV is required when using cardTokenId`, `Invalid or expired confirmation token`, `Email already registered` | Corrija os dados ou o estado do recurso. Não repita igual | | `401` | Credencial ausente ou inválida | `Unauthorized` (`Não autorizado` em `fees-info`) | Confira a chave, os dois pontos antes do Base64 e o prefixo `Basic `. Nas rotas com chave pública, confira se usou `pk_` | | `403` | Sem permissão para a operação | `Acesso negado`, `Fast Connect not enabled.`, `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`, `Redisparo de webhook disponível apenas para cobranças de teste` | Confira o perfil de quem gerou a chave. No Connect, confirme a habilitação. Saque não existe no Modo Teste | | `404` | Recurso não encontrado ou fora do seu escopo | `Cobrança não encontrada`, `Customer not found`, `Subscription plan not found`, `SubMerchant not found`, `Merchant não encontrado`, `Merchant not found` | Confira o `id` e se ele pertence à conta da chave usada. No estorno, o `404` também indica cobrança que não está `paid` | | `409` | Conflito | `Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.`, `APPLE_PAY_DOMAIN_ALREADY_REGISTERED`, `CARD_VALIDATION_IN_PROGRESS` | No CNPJ, consulte o cadastro existente. No Apple Pay, repita a chamada. Na validação de cartão, aguarde a primeira terminar | | `413` e `415` | Arquivo grande demais ou de tipo não aceito (envio com token) | `FILE_TOO_LARGE`, `UNSUPPORTED_FILE_TYPE` | Envie PDF ou imagem (JPG, PNG, GIF, BMP ou WebP) de até 50 MB | | `422` | Regra de negócio violada | `Fees not configured`, `Já existe um reembolso para esta cobrança`, `Insufficient balance. Required: X, Available: Y`, `CARD_VALIDATION_FAILED` | Leia o motivo, corrija a regra violada e só então envie de novo | | `429` | Limite de tentativas atingido | `APPLE_PAY_RATE_LIMITED`, `CARD_VALIDATION_RATE_LIMITED` | Aguarde. Não repita em laço | ### Erros do servidor (5xx) | Código | Significado | Exemplos reais | O que fazer | | - | - | - | - | | `500` | Erro interno | `Internal server error`, `APPLE_PAY_PROVIDER_AUTH_FAILED` | Em consultas, tente de novo com espera crescente. Em criações, verifique antes se o recurso foi criado. Se persistir, fale com o suporte | | `501` | Operação não disponível para o método ou provedor | `Reembolso não implementado para este método de pagamento`, `Reembolso não disponível para este provedor de pagamento` | Não repita. Fale com o suporte | | `503` | Serviço indisponível | `APPLE_PAY_PROVIDER_UNAVAILABLE` | Tente de novo mais tarde, com espera crescente | ## Quando repetir uma requisição O desenho abaixo mostra quando repetir uma requisição, conforme o código recebido e o tipo de operação. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB R(["Resposta da API
ou timeout"]):::neutro Q{"Código HTTP"}:::decisao S2["Concluída, não repita
na cobrança, leia o status"]:::ok S4["Nada foi feito
corrija antes de reenviar"]:::erro Q409{"Registro de domínio
Apple Pay?"}:::decisao AP["Repita: volta o
registro existente"]:::ok S429["Espere e repita"]:::alerta QG{"É consulta
GET?"}:::decisao RG["Repita com espera
crescente: 1, 2 e 4 s"]:::alerta VER["Verifique se o efeito
aconteceu e só repita
se não aconteceu"]:::alerta S501["Não repita
fale com o suporte"]:::erro R --> Q Q -->|"2xx"| S2 Q -->|"400 · 401 · 403
404 · 422"| S4 Q -->|"409"| Q409 Q409 -->|"sim"| AP Q409 -->|"não"| S4 Q -->|"429"| S429 Q -->|"500 · 503
ou timeout"| QG QG -->|"sim"| RG QG -->|"não: criação
ou ação"| VER Q -->|"501"| S501 classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` | Resultado | Consulta (`GET`) | Criação ou ação (`POST`, `PUT`, `PATCH`, `DELETE`) | | - | - | - | | `2xx` | Concluída | Concluída. Não repita | | `400`, `401`, `403`, `404`, `422` | Não repita sem corrigir | Não repita sem corrigir. Nada foi feito | | `409` | Não se aplica | No registro de domínio Apple Pay, repita: a API devolve o registro existente. Nos demais casos, corrija antes | | `429` | Repita depois de esperar | Repita depois de esperar | | `500`, `503` ou timeout | Repita com espera crescente | **Verifique primeiro** se o efeito aconteceu. Só repita se não aconteceu | | `501` | Não repita | Não repita. A operação não existe para aquele método ou provedor | > [!WARNING] > > A API não tem `Idempotency-Key`: antes de repetir um `POST /v1/charges` depois de um `500` ou timeout, siga o procedimento em [Idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia#idempotência). ## Como tratar no código ```javascript Node.js theme={null} class FinviaError extends Error { constructor(status, corpo) { const msg = Array.isArray(corpo?.message) ? corpo.message.join('; ') : corpo?.message; super(msg || `HTTP ${status}`); this.status = status; this.codigo = corpo?.code ?? (corpo?.statusCode ? undefined : corpo?.error); this.corpo = corpo; } } async function chamarFinvia(metodo, rota, corpo) { const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 60000); // o cartão é processado de forma síncrona try { const res = await fetch(`https://api-global.fastpaybrasil.com${rota}`, { method: metodo, headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: corpo ? JSON.stringify(corpo) : undefined, signal: controller.signal, }); // 204 não tem corpo const texto = await res.text(); const json = texto ? JSON.parse(texto) : null; if (!res.ok) { console.error('Erro Finvia', { metodo, rota, status: res.status, corpo: json }); throw new FinviaError(res.status, json); } return json; } finally { clearTimeout(timer); } } async function comRetentativa(fn, tentativas = 3) { for (let i = 0; i < tentativas; i++) { try { return await fn(); } catch (e) { const transitorio = e.name === 'AbortError' || e.status >= 500 || e.status === 429; if (!transitorio || i === tentativas - 1) throw e; await new Promise((r) => setTimeout(r, 1000 * 2 ** i)); // 1 s, 2 s, 4 s } } } // Consultas podem usar retentativa direta. // GET /v1/charges/{id} com id inexistente responde 200 com corpo vazio (json === null). const cobranca = await comRetentativa(() => chamarFinvia('GET', `/v1/charges/${id}`)); if (!cobranca) console.log('Cobrança não encontrada'); // Criações não: em caso de 5xx ou timeout, verifique antes de repetir. ``` ### Recusa de cartão: trate como resultado de negócio ```javascript Node.js theme={null} const charge = await chamarFinvia('POST', '/v1/charges', pedido); switch (charge.status) { case 'paid': // Aprovada break; case 'refused': case 'failed': // Mostre uma mensagem amigável e ofereça Pix ou outro cartão. // Guarde charge.reason no log para análise. break; case 'pending': // Pix: mostre o QR Code e aguarde o webhook charge.paid break; default: // in_analysis, authentication_required e outros: aguarde a notificação break; } ``` ## Boas práticas * **Registre o corpo completo do erro** com rota, método, código HTTP e horário. Sem dados de cartão e sem a chave. * **Não repita erros `4xx`** sem corrigir a causa. Eles indicam que nada foi feito. * **Repita `5xx` e timeouts só com verificação prévia** nas operações que criam ou alteram algo. * **Use espera crescente** entre tentativas (por exemplo, 1, 2 e 4 segundos) e um limite de tentativas. * **Defina um timeout** nas suas chamadas para não deixar o checkout preso. * **Separe mensagem técnica de mensagem ao cliente.** O `message` da API vai para o log. O cliente vê um texto amigável com a próxima ação possível. * **Monitore a taxa de erros** por rota. Um aumento de `401` pode indicar chave trocada; de `403`, permissão do usuário que gerou a chave; de `422`, mudança na configuração da conta ou no payload enviado. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` em todas as rotas | Base64 sem os dois pontos, chave errada ou ambiente trocado | Decodifique o cabeçalho e confira se termina em `:` | | `401` só nas rotas de 3DS | Chave secreta usada onde o contrato pede a chave pública | Use `pk_` nas rotas `/v1/three-ds/*` e em `resume-3ds` | | `403` com `Acesso negado` ao criar cobrança ou assinatura | Perfil do usuário que gerou a chave | Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave) | | `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie `shippingAddress` com `postalCode`, `addressLine1`, `city`, `state` e `country` | | `404` com `Cobrança não encontrada` no estorno | A cobrança não está `paid` (pendente, já estornada ou em chargeback) | Consulte a cobrança antes de pedir o estorno | | `422` com `Já existe um reembolso para esta cobrança` | Segundo pedido de estorno da mesma cobrança | Não repita. Consulte a cobrança | | `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Saque pedido com a chave de teste | Saques só existem em produção | | O código quebra ao ler `message` | Em erros de validação, `message` é uma lista | Trate `message` como texto ou lista | | Erro tratado como sucesso | O código leu só `201` e ignorou `status` | Sempre leia `status` na resposta da cobrança | ## Perguntas frequentes > [accordion] A recusa do cartão aparece como erro HTTP? > > Não. A cobrança é criada com `201`, e o `status` vem `refused` ou `failed`, com o motivo em `reason`. Trate como resultado de negócio e ofereça outra forma de pagamento. > [accordion] Posso mostrar o message da API para o cliente final? > > Não é recomendado. As mensagens são técnicas e misturam português e inglês. Mostre um texto próprio e guarde o `message` no log. A exceção é o `CARD_VALIDATION_FAILED`, cujo `message` foi feito para exibição. > [accordion] Recebi 500 ao criar uma cobrança. A cobrança existe? > > Pode existir. Antes de repetir, siga a verificação descrita em [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia). > [accordion] Onde vejo todas as mensagens possíveis de uma rota? > > No [Catálogo de códigos de erro](/anexos/codigos-de-erro), agrupado por rota, e na página de referência de cada rota. ## Como testar * Envie uma requisição sem o cabeçalho `Authorization` e confira o tratamento do `401`. * Envie um item `physical` sem `shippingAddress` e confira o tratamento do `400` (cenário **CHG-10**). * Envie um corpo com um campo obrigatório faltando e confira se o seu código lê `message` como lista. * Consulte um `id` inexistente em `GET /v1/charges/{id}` e confira se o seu código trata o `200` com corpo vazio. * Crie uma cobrança com o cartão de teste `4444333322221112` e confira o tratamento de `refused` (cenário **CHG-03** do [roteiro de homologação](/homologacao/roteiro)). * Em split, comprove que a sua integração trata a rejeição de percentual inválido e de `merchantId` fora do grupo (cenários **SPL-03** e **SPL-04**). ## Veja também > [card] [Catálogo de códigos de erro](/anexos/codigos-de-erro) > > Todas as mensagens literais, por rota. > [card] [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia) > > Como repetir sem duplicar. > [card] [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) > > Chaves, permissões e autenticação. > [card] [Status de cobrança](/anexos/status-de-cobranca) > > O que fazer em cada status. # Paginação, ordenação e idempotência Source: https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia Como percorrer listagens, ordenar resultados e evitar cobranças e processamentos duplicados quando algo dá errado na rede. Três assuntos valem para a API inteira: como as listagens devolvem os dados em páginas, em que ordem os resultados vêm e como evitar que uma falha de rede vire uma cobrança duplicada. Esta página reúne os três, com as diferenças entre rotas que você precisa tratar no código. > [!NOTE] > > **Para o negócio:** a API da Finvia não tem proteção automática contra requisições repetidas. Se o sistema reenvia uma criação de cobrança depois de uma falha de rede, o cliente pode ser cobrado duas vezes. O procedimento desta página evita isso e deve estar no escopo de qualquer integração. ## Paginação Todas as listagens paginadas da API usam os mesmos dois parâmetros de consulta: | Parâmetro | Tipo | Padrão | Descrição | | - | - | - | - | | `page` | integer | `1` | Número da página. Começa em 1 | | `size` | integer | `10` | Quantidade de itens por página | > [!WARNING] > > O parâmetro de tamanho é `size`. A API ignora `limit` sem dar erro: `limit=10` parece funcionar só porque 10 já é o padrão, e `limit=50` continua devolvendo 10 itens. O mesmo vale para qualquer parâmetro desconhecido, que é ignorado em silêncio. Confira sempre o nome do filtro na referência da rota. ```bash theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/charges?page=2&size=20" \ -u "$FINVIA_API_KEY:" ``` ### Formato da resposta em cada listagem Há dois modelos de resposta paginada e algumas rotas que devolvem a lista inteira, sem paginação. **Modelo A: totais na raiz do objeto** ```json theme={null} { "data": [ ], "total": 100, "page": 1, "size": 10, "pages": 10 } ``` **Modelo B: totais dentro de `meta`** ```json theme={null} { "data": [ ], "meta": { "total": 100, "page": 1, "limit": 10, "totalPages": 10 } } ``` No modelo B, o `meta.limit` da resposta é só o tamanho da página que você pediu em `size`. Ele não é um parâmetro de consulta. | Rota | Paginada | Formato da resposta | Ordem dos resultados | Filtros | | - | - | - | - | - | | [`GET /v1/charges`](/referencia/cobrancas/listar) | Sim | Modelo A | Sempre da mais recente para a mais antiga. `orderBy` é ignorado | `status`, `currency`, `createdAtStart` + `createdAtEnd`, `searchFor`, `merchantId` | | [`GET /v1/submerchants`](/referencia/fast-connect/listar-subcontas) | Sim | Modelo A | Mais recentes primeiro. Aceita `orderBy` com nomes em snake\_case | `status`, `search`, `createdFrom`, `createdTo`, `completeness`, `companyTaxId`, `legalName`, `tradeName` | | [`GET /v1/payout-requests`](/referencia/saques/listar) | Sim | Modelo A, com o campo extra `pendingCount` | Mais recentes primeiro. Não use `orderBy` | `merchantId`, `status`, `currency`, `createdAtStart`, `createdAtEnd` | | [`GET /v1/customers`](/referencia/clientes/listar) | Sim | Modelo A | Mais recentes primeiro | `search`, `email`, `documentId` | | [`GET /v1/subscription-plans`](/referencia/planos/listar) | Sim | Modelo B | Não aceita `orderBy` | `merchantId`, `status` | | [`GET /v1/subscriptions`](/referencia/assinaturas/listar) | Sim | Modelo B | Não aceita `orderBy` | `merchantId`, `customerId`, `status`, `search` | | [`GET /v1/webhook-endpoints`](/referencia/webhooks/listar-endpoints) | Sim | Modelo A | Não aceita `orderBy` | `merchantId`, `search` | | [`GET /v1/submerchants/{merchantId}/legal-representatives`](/referencia/fast-connect/listar-representantes) | Não | Objeto com `data` (lista) | Representante legal primeiro | `include=documents` | | [`GET /v1/apple-pay/domains`](/referencia/apple-pay/listar-dominios) | Não | Objeto com `data` (lista) | Mais recentes primeiro | Nenhum | | [`GET /v1/cards`](/referencia/cartoes/listar) | Não | Lista (array) direto na raiz, com no máximo os 20 cartões mais recentes | Mais recentes primeiro | `customerId` | | [`GET /v1/wallets`](/referencia/carteiras/listar) | Não | Lista (array) direto na raiz | Não se aplica | `merchantId` (obrigatório), `currency` | | [`GET /v1/payment-methods`](/referencia/meios-de-pagamento/listar) | Não | Lista (array) direto na raiz | Não se aplica | `merchantId`, `currency` | > [!TIP] > > **Para o desenvolvedor:** escreva um leitor de paginação que aceite os dois modelos. No modelo A, o total de páginas está em `pages`. No modelo B, está em `meta.totalPages`. Rotas que devolvem array não têm página seguinte. ### Como percorrer todas as páginas ```javascript Node.js theme={null} // listar-tudo.mjs (Node.js 18+, ESM, await no topo) const API_URL = 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); async function listarTudo(rota, filtros = {}) { const itens = []; let page = 1; let totalPaginas = 1; do { const params = new URLSearchParams({ ...filtros, page: String(page), size: '50' }); const res = await fetch(`${API_URL}${rota}?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); if (!res.ok) throw new Error(`Falha ${res.status} em ${rota}`); const corpo = await res.json(); itens.push(...corpo.data); // Modelo A (pages) ou modelo B (meta.totalPages) totalPaginas = corpo.pages ?? corpo.meta?.totalPages ?? 1; page += 1; } while (page <= totalPaginas); return itens; } const pagas = await listarTudo('/v1/charges', { status: 'paid' }); console.log(`${pagas.length} cobranças pagas`); ``` > [!NOTE] > > A documentação não informa um valor máximo para `size`. Comece com valores moderados, como 20 ou 50, e ajuste conforme o tempo de resposta. Em clientes, `page` ou `size` menor que 1, ou não numérico, volta ao padrão. ## Ordenação A maior parte das listagens devolve os registros do mais recente para o mais antigo, e essa ordem não pode ser trocada. O parâmetro `orderBy` só funciona em `GET /v1/submerchants`. | Rota | Como fica a ordem | | - | - | | `GET /v1/charges` | Sempre da mais recente para a mais antiga. A rota ignora `orderBy` | | `GET /v1/payout-requests` | Do mais recente para o mais antigo. Não envie `orderBy`: valores como `createdAt,-amount` geram erro `500` | | `GET /v1/submerchants` | Sem `orderBy`, por data de criação decrescente. Com `orderBy`, use os nomes das colunas em snake\_case | | Demais listagens | A ordem padrão de cada rota, descrita na referência | Formato do `orderBy` em subcontas: | Formato | Direção | Exemplo | | - | - | - | | `campo` | Crescente (mais antigo primeiro, A a Z) | `orderBy=created_at` | | `-campo` | Decrescente (mais novo primeiro, Z a A) | `orderBy=-created_at` | | Vários campos | Separados por vírgula, aplicados em ordem | `orderBy=legal_name,-created_at` | > [!WARNING] > > Em subcontas, o `orderBy` com nomes em camelCase (como `legalName,-createdAt`) gera erro `500`. Use `legal_name,-created_at`. ```bash theme={null} # Subcontas em ordem alfabética de razão social curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants?page=1&size=20&orderBy=legal_name,-created_at" \ -u "$FINVIA_API_KEY:" ``` > [!TIP] > > **Para o desenvolvedor:** em cobranças, novos registros entram no início da listagem. Se você percorre muitas páginas enquanto novas cobranças chegam, um item pode aparecer em duas páginas seguidas. Deduplique pelo `id` ou restrinja a leitura a um período fechado com `createdAtStart` e `createdAtEnd`. ## Idempotência Idempotência é a garantia de que repetir uma operação produz o mesmo efeito que executá-la uma vez. Ela importa sempre que a sua aplicação não sabe se uma requisição chegou ao destino, como num timeout ou numa queda de conexão. > [!WARNING] > > O cabeçalho `Idempotency-Key` não existe hoje na API da Finvia. `POST /v1/charges` não lê nenhum cabeçalho de idempotência, então cada chamada cria uma cobrança nova. Reenviar a criação depois de um timeout pode gerar uma segunda cobrança para o mesmo pedido; no cartão, isso é cobrança em dobro. ### Regra geral Repita uma requisição só depois de confirmar que a primeira não produziu efeito. | Situação | É seguro repetir? | O que fazer | | - | - | - | | Resposta `4xx` (`400`, `401`, `403`, `404`, `422`) | Não, sem corrigir antes | A requisição foi rejeitada. Corrija o problema e só então envie de novo | | Resposta `5xx` ou timeout em uma criação | Só depois de verificar | O resultado é incerto. Siga o procedimento abaixo | | Timeout em uma consulta (`GET`) | Sim | Consultas não alteram nada | ### Procedimento depois de um timeout ao criar cobrança Depois de um timeout, você não tem o `id` da cobrança. Consultar `GET /v1/charges/{id}` com o número do seu pedido não resolve: para um `id` que não existe, a API responde hoje `200` com corpo vazio, sem `404`. O caminho é este: O desenho abaixo resume a decisão depois de uma criação de cobrança sem resposta clara. Os passos a seguir detalham cada etapa. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% flowchart TB A(["POST /v1/charges com
metadata.orderId do pedido"]):::lojista Q1{"Que resposta
chegou?"}:::decisao OK["Guarde o id
junto com o pedido"]:::ok E4["Nada foi criado
corrija e só então reenvie"]:::erro NO["Não reenvie o POST
de imediato"]:::alerta Q2{"charge.created
com o orderId?"}:::decisao BUS["Busque em GET /v1/charges
mesma chave e mesmo dia
searchFor: doc. ou e-mail"]:::lojista Q3{"Mesmo metadata
e amount?"}:::decisao MID["Perto da meia-noite UTC?
repita com o dia vizinho"]:::neutro ACH(["Associe o id ao pedido
e siga o fluxo"]):::ok NOVO(["Não foi criada:
é seguro criar de novo"]):::ok A --> Q1 Q1 -->|"2xx"| OK Q1 -->|"400 · 401 · 403
404 · 422"| E4 Q1 -->|"5xx ou timeout"| NO NO --> Q2 Q2 -->|"sim"| ACH Q2 -->|"não"| BUS BUS --> Q3 Q3 -->|"sim"| ACH Q3 -->|"não"| MID MID -->|"ainda não achou"| NOVO classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00 classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15 classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209 classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828 classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054 classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23 ``` **1. Não reenvie o POST de imediato** Se a primeira chamada chegou, um novo `POST /v1/charges` cria uma segunda cobrança. **2. Mande sempre o identificador do pedido em metadata** Em toda criação, envie o número do seu pedido em `metadata`, por exemplo `{"orderId": "PED-1001"}`. É ele que liga a cobrança ao pedido quando o `id` se perde. **3. Recupere o id pelo webhook charge.created** Cadastre um endpoint de webhook com o evento `charge.created`. Ele é emitido assim que a cobrança é gravada, antes da resposta do processador, e traz em `data` o `id` da cobrança e o `metadata` com as chaves exatamente como você enviou. É a forma mais confiável de recuperar o `id` depois de um timeout. **4. Busque na listagem** Se o webhook não chegou, procure a cobrança com a **mesma chave** usada na criação (a chave de teste lista só cobranças de teste, e a de produção só as de produção): `GET /v1/charges?createdAtStart=AAAA-MM-DD&createdAtEnd=AAAA-MM-DD&searchFor=&size=50` Use como termo o documento ou o e-mail do comprador. Depois compare `metadata` e `amount` do seu lado. **5. Decida** Encontrou a cobrança: associe o `id` ao pedido e siga o fluxo. Não encontrou: a cobrança não foi criada e é seguro tentar de novo. Regras da busca em `GET /v1/charges`: | Item | Regra | | - | - | | `createdAtStart` e `createdAtEnd` | Datas `AAAA-MM-DD`. Precisam vir juntas. O filtro pega o dia inteiro, no fuso do servidor (UTC) | | `searchFor` | Busca parcial, sem diferenciar maiúsculas, em: nome, e-mail, documento e telefone do comprador; seis primeiros e quatro últimos dígitos do cartão; título do primeiro item; `pspRefId`; `endToEndId` do Pix; e nome da conta | | Outros filtros | `status`, `currency`, `page` e `size` | | Ordem | Sempre da mais recente para a mais antiga | | Tentativas agrupadas | No cartão, tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas. A listagem mostra só a principal do grupo; as demais aparecem em `groupCharges` no `GET /v1/charges/{id}` da principal | | Chaves de `metadata` | Envie em camelCase (`orderId`) para ler a mesma chave na listagem e no webhook. Chaves em snake\_case voltam convertidas nas respostas de `GET`. Veja [Metadata](/guias/cobrancas/visao-geral#metadata) | > [!TIP] > > **Para o desenvolvedor:** use um timeout de cliente generoso na criação, por exemplo 60 segundos. O cartão é processado de forma síncrona, e um timeout curto aumenta as chances de você não saber o resultado. ```javascript Node.js theme={null} // localizar-cobranca.mjs (Node.js 18+, ESM, await no topo) const API_URL = 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); async function localizarCobranca(pedido) { const dia = new Date(pedido.tentativaEm).toISOString().slice(0, 10); // AAAA-MM-DD em UTC const params = new URLSearchParams({ createdAtStart: dia, createdAtEnd: dia, searchFor: pedido.email, page: '1', size: '50', }); const res = await fetch(`${API_URL}/v1/charges?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); const { data } = await res.json(); // A chave orderId foi enviada em camelCase e volta igual na listagem. return data.find((c) => c.amount === pedido.amount && c.metadata?.orderId === pedido.orderId ); } const encontrada = await localizarCobranca({ orderId: 'PED-1001', amount: 150, email: 'maria.souza@email.com', tentativaEm: Date.now(), }); console.log(encontrada ? `Cobrança já existe: ${encontrada.id}` : 'Nenhuma cobrança encontrada: pode criar de novo'); ``` > [!NOTE] > > Se a tentativa aconteceu perto da meia-noite em UTC, repita a busca com o dia anterior ou o seguinte, porque o filtro de datas usa o fuso do servidor. ### Proteções que a própria API oferece Algumas operações já têm comportamento que evita duplicidade. Use-as a seu favor, sem dispensar a verificação acima. | Operação | Comportamento | | - | - | | Estorno (`POST /v1/refunds`) | Cada cobrança aceita um único estorno. Um segundo pedido recebe `422` com `Já existe um reembolso para esta cobrança`. Uma cobrança que já não está `paid` (inclusive já estornada) recebe `404` com `Cobrança não encontrada` | | Registro de domínio Apple Pay (`POST /v1/apple-pay/domains`) | Registrar de novo o mesmo hostname na mesma conta devolve o mesmo registro, também com `201` | | Validação de cartão no trial grátis | Reenviar a mesma criação de assinatura (mesmo cliente, cartão e plano) em até 15 minutos reaproveita a validação aprovada e não cobra o R\$ 1,00 de novo. Uma validação do mesmo cartão em andamento responde `409` com `CARD_VALIDATION_IN_PROGRESS` | > [!WARNING] > > O reaproveitamento da validação no trial grátis não impede a criação de uma segunda assinatura. Antes de repetir `POST /v1/subscriptions` depois de um timeout, liste as assinaturas do cliente com `GET /v1/subscriptions?customerId=...` e confira se a primeira foi criada. ## Idempotência no recebimento de webhooks O mesmo evento pode chegar mais de uma vez. Isso acontece, por exemplo, quando a mesma URL está cadastrada como endpoint e como `postbackUrl`, ou em novas tentativas de entrega (veja a política de entrega em [Webhooks](/guias/webhooks/visao-geral)). O seu receptor precisa reconhecer eventos repetidos. A chave de deduplicação de cada formato (envelope padrão, `charge.updated`, saque e conta) está na [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos), com exemplo completo em Node.js e PHP. > [!TIP] > > **Para o desenvolvedor:** guarde as chaves processadas em armazenamento persistente (banco ou Redis), não em memória. Um `Set` em memória se perde a cada reinício do servidor. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | A listagem ignora o tamanho pedido | Uso de `limit` na query | Use `size` | | A ordem não muda em cobranças | `GET /v1/charges` ignora `orderBy` | A ordem é sempre da mais recente para a mais antiga. Use `createdAtStart` e `createdAtEnd` para restringir o período | | Erro `500` ao listar subcontas ou saques com `orderBy` | Nomes em camelCase em subcontas, ou `orderBy` em saques | Em subcontas, use snake\_case (`legal_name,-created_at`). Em saques, não envie `orderBy` | | Filtro sem efeito | Parâmetro com nome que a rota não conhece (ex.: `createdAt` em saques) | A API ignora parâmetros desconhecidos sem erro. Confira o nome na referência da rota | | O código quebra ao ler `pages` em planos ou assinaturas | Essas rotas usam o modelo B, com `meta.totalPages` | Leia os dois modelos | | O código quebra ao ler `data` em cartões ou carteiras | `GET /v1/cards` e `GET /v1/wallets` devolvem array direto | Trate a resposta como lista | | `metadata.order_id` não encontrado na listagem | Chaves enviadas em snake\_case voltam em camelCase nas respostas de `GET` | Leia `metadata.orderId` ou envie as chaves em camelCase. Veja [Metadata](/guias/cobrancas/visao-geral#metadata) | | Cobrança duplicada para o mesmo pedido | Reenvio automático de `POST /v1/charges` depois de timeout | Siga o procedimento de timeout desta página | | Pedido liberado duas vezes | Webhook repetido processado de novo | Aplique a [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos) | ## Perguntas frequentes > [accordion] Posso buscar uma cobrança pelo número do meu pedido? > > Não diretamente. `GET /v1/charges` não filtra por `metadata`. Guarde o `id` devolvido na criação junto com o pedido. Para recuperar uma cobrança sem o `id`, use o webhook `charge.created` ou a busca por período e `searchFor`, descritos no procedimento de timeout. > [accordion] Qual é o tamanho padrão da página? > > `10`, em todas as listagens paginadas (cobranças, clientes, planos, assinaturas, subcontas, saques e endpoints de webhook). > [accordion] Todas as listagens aceitam orderBy? > > Não. Só `GET /v1/submerchants` aceita `orderBy`, com nomes em snake\_case. Em cobranças ele é ignorado, e em saques gera erro. As demais listagens têm ordem fixa. > [accordion] Existe Idempotency-Key? > > Não existe hoje. Use o identificador do pedido em `metadata` e o procedimento de timeout desta página. > [accordion] Se o webhook chegar duas vezes, a Finvia considera erro? > > Não. Reentregas fazem parte do funcionamento. Responda com status `2xx` também para o evento repetido e apenas não o processe de novo. ## Como testar * Liste cobranças com `page` e `size` e confira a paginação (base do cenário **CHG-06** do [roteiro de homologação](/homologacao/roteiro)). * Use `POST /v1/charges/{id}/resend-webhook` duas vezes com o mesmo status e confirme que o seu receptor responde `2xx` nas duas vezes e não repete o efeito, como liberar o pedido (cenários **CHG-08** e **CHG-09**). Cada simulação gera um evento com `id` novo, então quem segura a repetição é a checagem do pedido. * Simule um timeout no seu código (por exemplo, abortando a requisição antes da resposta) e confira se a rotina encontra a cobrança pelo `charge.created` ou pela listagem antes de criar outra. ## Veja também > [card] [Erros e como tratar](/primeiros-passos/erros) > > Quando repetir e quando corrigir uma requisição. > [card] [Listar cobranças](/referencia/cobrancas/listar) > > Referência de `GET /v1/charges`. > [card] [Webhooks](/guias/webhooks/visao-geral) > > Entrega e segurança das notificações. > [card] [Catálogo de eventos](/anexos/catalogo-de-eventos) > > Todos os eventos e seus envelopes. # Sua primeira cobrança Source: https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca Tutorial completo no sandbox: autentique, crie uma cobrança Pix, receba os webhooks, simule outros status e repita com cartão de crédito. Este tutorial leva você da chave de teste até uma cobrança acompanhada por webhook, sem dinheiro real. Ao final, você terá o fluxo básico que toda integração com a Finvia usa: criar a cobrança, mostrar o meio de pagamento ao cliente, receber a notificação e confirmar o estado. > [!NOTE] > > **Para o negócio:** este é o mesmo caminho que o seu checkout vai percorrer em produção. Os cenários feitos aqui servem de base para os cenários CHG-01 a CHG-09 do [roteiro de homologação](/homologacao/roteiro), a etapa recomendada antes de ir para produção. ## O que você vai precisar * A **chave secreta de teste** (`sk_test_`), gerada por um usuário Owner ou Manager. Como gerar: [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes#onde-obter-as-chaves). * Pix habilitado na conta (taxa de Pix em reais configurada). Sem isso, a criação do Pix responde `422` com `Fees not configured`, também no Modo Teste. * Terminal com `curl`, ou Node.js 18 ou superior. * Uma URL pública com HTTPS que aponte para a sua máquina, para receber os webhooks. No desenvolvimento, ferramentas como o ngrok fazem isso (`ngrok http 3000`). > [!WARNING] > > Use somente a chave `sk_test_` neste tutorial. Com a chave de produção (`sk_`), as cobranças são reais. ## Visão geral do fluxo O desenho abaixo mostra a sequência completa do tutorial com Pix no sandbox, da conexão à consulta final. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(243,245,248) Sua aplicação participant S as Seu script ou servidor participant R as Seu receptor (ngrok) end box rgb(234,243,255) Finvia participant F as Finvia API (sandbox) end S->>F: GET /v1/payment-methods (Basic com sk_test_) F-->>S: 200 · lista de meios habilitados S->>F: POST /v1/charges (type pix, postbackUrl) F-->>S: 201 · pending · copyPaste · qrCodeBase64 Note over S,R: Guarde o id junto com o pedido e mostre o QR Code F-)R: charge.created e charge.pending R-->>F: 200 OK Note over R,F: No Modo Teste, o Pix vira paid sozinho em cerca de 5 s F-)R: charge.paid (mesmo id da criação) R-->>F: 200 OK, libera o pedido uma vez S->>F: POST /v1/charges/{id}/resend-webhook (status refunded) F-->>S: 201 · deliveries F-)R: charge.refunded simulado, com id novo S->>F: GET /v1/charges/{id} F-->>S: 200 · status paid (a simulação não altera a cobrança) ``` **1. Autenticar e testar a conexão** Monte o cabeçalho Basic e chame `GET /v1/payment-methods`. **2. Subir o receptor de webhooks** Um servidor mínimo que recebe os avisos da Finvia e responde com status `2xx`. **3. Criar a cobrança Pix** `POST /v1/charges` com `postbackUrl` apontando para o seu receptor. **4. Mostrar o QR Code** Use `qrCodeBase64` e `copyPaste` da resposta. **5. Receber os eventos** Veja `charge.created` e `charge.pending` chegarem e, cerca de 5 segundos depois, o `charge.paid`: no Modo Teste, o Pix é confirmado sozinho. **6. Simular outros status** Use a rota de simulação de webhook do sandbox para testar o tratamento de estorno, recusa e falha. **7. Consultar a cobrança** `GET /v1/charges/{id}` para confirmar o estado. **8. Repetir com cartão de crédito** O resultado do cartão vem na própria resposta. ## 1. Autentique e teste a conexão A API usa HTTP Basic: a chave vai como usuário, a senha fica vazia. Você converte `sua_chave:` (com os dois pontos no final) para Base64 e envia no cabeçalho `Authorization`. Configure as variáveis de ambiente: ```bash theme={null} export FINVIA_API_URL="https://api-global.fastpaybrasil.com" export FINVIA_API_KEY="sk_test_sua_chave_de_teste" ``` Chame a listagem de meios de pagamento. Resposta `200` significa que a chave e o cabeçalho estão corretos. ```http REST (JSON) theme={null} GET /v1/payment-methods HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "$FINVIA_API_URL/v1/payment-methods" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} // conexao.mjs (Node.js 18+, ESM, await no topo) const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch(`${API_URL}/v1/payment-methods`, { headers: { Authorization: `Basic ${credentials}` }, }); console.log(response.status, await response.json()); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/payment-methods", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payment-methods")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/payment-methods"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/payment-methods", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/payment-methods") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` A resposta é uma lista com os meios habilitados para a sua conta. Cada item traz `id`, `name`, `countries`, `currencies` e `description`. > [!TIP] > > Recebeu `200` e uma lista em JSON? A autenticação está pronta. Se recebeu `401` com `{"message": "Unauthorized", "statusCode": 401}`, decodifique o Base64 e confira se ele termina em `:`. ## 2. Suba o receptor de webhooks O **webhook** é a notificação que a Finvia envia ao seu servidor quando algo muda na cobrança. No Pix, ele é a única forma de saber que o cliente pagou sem ficar consultando a API. Este servidor mínimo em Express recebe as notificações e responde `200` antes de processar. Ele descarta repetições com a [receita de deduplicação](/guias/webhooks/visao-geral#como-descartar-eventos-repetidos) e, além disso, só libera um pedido que ainda não foi liberado. Essa segunda proteção cobre o caso de o mesmo aviso chegar com outro `id`. ```javascript server.mjs theme={null} // server.mjs (Node.js 18+, ESM) import express from 'express'; const app = express(); app.use(express.json()); // Em produção, guarde estes dados em banco ou Redis. const processados = new Set(); const pedidosLiberados = new Set(); // Receita de deduplicação da visão geral de webhooks (resumida para cobranças) function dedupKey(body) { if (body.id) return `evt:${body.id}`; if (body.event === 'charge.updated') { const d = body.data ?? {}; return ['charge.updated', d.id, d.status, d.isBlocked ?? '', d.chargebackAlertRefunded ?? '', d.updatedAt ?? ''].join(':'); } return null; } app.post('/webhooks/finvia', (req, res) => { const { event, data } = req.body; // Responda rápido. A lógica de negócio roda depois. res.status(200).send('OK'); const key = dedupKey(req.body); if (key && processados.has(key)) return; if (key) processados.add(key); console.log(`Evento ${event} | cobrança ${data?.id} | status ${data?.status}`); // Os mesmos endpoints recebem eventos de teste e de produção. if (req.body.livemode === false && process.env.NODE_ENV === 'production') return; switch (event) { case 'charge.created': // Cobrança gravada: associe data.id ao pedido (data.metadata volta como foi enviada). break; case 'charge.pending': // QR Code gerado: o pedido aguarda pagamento. break; case 'charge.paid': // Pagamento confirmado: libere o pedido uma única vez. // Em produção, confirme antes com GET /v1/charges/{id}. if (pedidosLiberados.has(data.id)) { console.log('Pedido já liberado, nada a fazer'); break; } pedidosLiberados.add(data.id); console.log('Pedido liberado'); break; case 'charge.refused': case 'charge.failed': // Recusa ou falha: o pedido não foi pago. break; case 'charge.refunded': // Estorno concluído: registre a devolução. break; case 'charge.updated': // Canal legado, só na postbackUrl, em camelCase e sem id no envelope. break; default: console.log('Evento não tratado:', event); } }); app.listen(3000, () => console.log('Receptor ouvindo na porta 3000')); ``` ```bash theme={null} npm install express node server.mjs ngrok http 3000 ``` Anote a URL HTTPS gerada pelo ngrok, por exemplo `https://abc123.ngrok.io`. O endereço do seu receptor será `https://abc123.ngrok.io/webhooks/finvia`. > [!TIP] > > **Para o desenvolvedor:** os eventos `charge.created`, `charge.pending`, `charge.paid` e `charge.refunded` usam campos em snake\_case dentro de `data` (`paid_at`, `payment_details`, `is_test`). A resposta da API usa camelCase (`paidAt`, `paymentDetails`). Não reaproveite o mesmo parser para os dois sem mapear os nomes. Os objetos aninhados (`payment_details`, `payment_method` de cartão) ficam em camelCase, e `metadata` volta exatamente como foi enviada. O `charge.updated` legado vem todo em camelCase, inclusive as chaves de `metadata`. Por isso os exemplos usam `orderId`, que chega igual em todos os canais (veja [Metadata](/guias/cobrancas/visao-geral#metadata)). ## 3. Crie a cobrança Pix Esta é a cobrança do exemplo de início rápido: R\$ 100,00 em Pix, com validade de 1 dia, para um produto digital. A `postbackUrl` aponta para o seu receptor. ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "$FINVIA_API_URL/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" }' ``` ```javascript Node.js theme={null} // criar-pix.mjs (Node.js 18+, ESM, await no topo) const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch(`${API_URL}/v1/charges`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 100, currency: 'BRL', customer: { name: 'Joao Silva', email: 'joao@email.com', document: { type: 'cpf', id: '52998224725' }, phone: '+5511987654321', address: { country: 'BRA' }, }, paymentMethod: { type: 'pix', expirationInDays: 1 }, items: [ { title: 'Produto XYZ', type: 'digital', description: 'Descrição do produto', unit_price: 100, quantity: 1, }, ], postbackUrl: 'https://abc123.ngrok.io/webhooks/finvia', }), }); const charge = await response.json(); console.log(response.status, charge); // Guarde charge.id junto com o seu pedido. ``` ```python Python theme={null} import os import requests payload = { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725", }, "phone": "+5511987654321", "address": { "country": "BRA", }, }, "paymentMethod": { "type": "pix", "expirationInDays": 1, }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1, }, ], "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 100, 'currency' => 'BRL', 'customer' => [ 'name' => 'Joao Silva', 'email' => 'joao@email.com', 'document' => [ 'type' => 'cpf', 'id' => '52998224725', ], 'phone' => '+5511987654321', 'address' => [ 'country' => 'BRA', ], ], 'paymentMethod' => [ 'type' => 'pix', 'expirationInDays' => 1, ], 'items' => [ [ 'title' => 'Produto XYZ', 'type' => 'digital', 'description' => 'Descrição do produto', 'unit_price' => 100, 'quantity' => 1, ], ], 'postbackUrl' => 'https://abc123.ngrok.io/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 100, "currency" => "BRL", "customer" => { "name" => "Joao Silva", "email" => "joao@email.com", "document" => { "type" => "cpf", "id" => "52998224725", }, "phone" => "+5511987654321", "address" => { "country" => "BRA", }, }, "paymentMethod" => { "type" => "pix", "expirationInDays" => 1, }, "items" => [ { "title" => "Produto XYZ", "type" => "digital", "description" => "Descrição do produto", "unit_price" => 100, "quantity" => 1, }, ], "postbackUrl" => "https://abc123.ngrok.io/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201`: ```json theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "pending", "paymentDetails": { "endToEndId": "1231389", "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }, "reason": null } ``` O valor vai em reais: `"amount": 100` significa R\$ 100,00. Pontos de atenção nesta chamada: | Campo | Regra | | - | - | | `items[].type` | `physical` ou `digital`. Se algum item for `physical`, `shippingAddress` é obrigatório, com `postalCode`, `addressLine1`, `city`, `state` e `country` (`addressLine2` e `neighborhood` são opcionais). Sem o endereço, a API responde `400` e não cria a cobrança | | `paymentMethod.expirationInDays` | Mínimo `1`. Para validades curtas, use `expirationInSeconds`, com mínimo `900` (15 minutos) | | `postbackUrl` | Recebe os eventos da cobrança **depois** da criação. Ela não muda a resposta síncrona | Como escolher a validade do QR Code: veja o [guia de Pix](/guias/cobrancas/pix#como-escolher-a-validade). ## 4. Mostre o QR Code A resposta já traz tudo o que o cliente precisa para pagar: * `qrCodeBase64`: a imagem PNG do QR Code em formato data URI, pronta para usar como `src` de uma imagem. * `copyPaste`: o código Pix copia e cola, para quem paga pelo celular. No Modo Teste, o `copyPaste` e o `qrCodeBase64` são fictícios. Não tente pagar esse código em um aplicativo de banco: a confirmação acontece sozinha, como mostra o passo seguinte. ```html theme={null} QR Code Pix

Ou copie o código: 00020101021226870014br.gov.bcb.pix...6304ABCD

``` > [!TIP] > > **Para o desenvolvedor:** `qrCodeBase64` pode vir `null` ou ausente quando a imagem não pôde ser gerada. Nesse caso, gere o QR Code no seu front-end a partir do `copyPaste`. Sempre exiba o `copyPaste` também: muitos clientes pagam pelo celular e não conseguem ler a própria tela. ## 5. Receba os webhooks ### O que chega ao receptor Assim que a cobrança é gravada, sai o `charge.created`. Logo depois, com o QR Code gerado, sai o `charge.pending`. Os dois chegam à `postbackUrl` e aos endpoints cadastrados no painel (**Configurações > Webhooks**). Os eventos de cada canal estão na [tabela de eventos por canal](/guias/webhooks/visao-geral#eventos-por-canal). ```json theme={null} { "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q", "event": "charge.pending", "livemode": false, "data": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "pending", "amount": 100, "currency": "BRL", "payment_method": { "type": "pix" }, "payment_details": { "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }, "postback_url": "https://abc123.ngrok.io/webhooks/finvia", "paid_at": null, "is_test": true } } ``` O exemplo acima mostra os campos principais. O objeto `data` completo está em [Webhooks de cobrança](/guias/webhooks/cobranca). ### O Pix de teste é pago sozinho No Modo Teste não há nada para pagar nem botão de simulação. Cerca de 5 segundos depois da criação, a cobrança passa sozinha para `paid`: `paidAt` é preenchido e `paymentDetails.endToEndId` recebe um valor de teste. Nesse momento chega o `charge.paid`, com o mesmo `id` de cobrança devolvido na criação. É nesse evento que você libera o pedido. > [!TIP] > > O `charge.paid` com o mesmo `id` retornado na criação é a evidência do cenário CHG-05 da homologação. Se, em casos raros, a cobrança não virar `paid` em alguns segundos, crie outra. > [!NOTE] > > No sandbox, todo Pix é aprovado. Não dá para simular expiração ou falha de um Pix. Para testar o tratamento desses casos, use a simulação de webhook abaixo. ### Separe eventos de teste e de produção Os endpoints de webhook não têm modo: a sua conta tem uma única lista, que recebe tanto os eventos de teste quanto os de produção. O painel não tem uma lista separada para o Modo Teste. Por isso, a integração precisa separar os eventos pelo payload: | Canal | Como reconhecer um evento de teste | | - | - | | Envelope padrão de cobrança (`charge.created`, `charge.paid`...) | `livemode: false` e `data.is_test: true` | | `charge.updated` legado (só na `postbackUrl`) | `data.isTest: true` | A `postbackUrl` é definida em cada cobrança. Se quiser URLs diferentes por ambiente, informe uma `postbackUrl` de teste nas cobranças criadas com a chave de teste. ### Simule outros status Para testar como o seu receptor reage a estorno, recusa ou falha, use a rota de simulação de webhook, disponível só para cobranças de teste. Ela **não reenvia** o evento original e **não altera** a cobrança: gera um evento novo `charge.{status}`, com `id` novo, para a `postbackUrl` e para os endpoints da sua conta. ```http REST (JSON) theme={null} POST /v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "status": "refunded" } ``` ```bash cURL theme={null} curl -X POST "$FINVIA_API_URL/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "status": "refunded" }' ``` ```javascript Node.js theme={null} // simular-webhook.mjs (Node.js 18+, ESM, await no topo) const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const chargeId = '2vorkDcXyvzifL63YX09S9VqcnI'; const response = await fetch(`${API_URL}/v1/charges/${chargeId}/resend-webhook`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ status: 'refunded' }), }); // 201, com o resultado de cada entrega console.log(response.status, await response.json()); ``` ```python Python theme={null} import os import requests payload = { "status": "refunded", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'refunded', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "status": "refunded" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "status": "refunded" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "status": "refunded" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "status" => "refunded", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Resposta `201`: ```json theme={null} { "deliveries": [ { "url": "https://abc123.ngrok.io/webhooks/finvia", "status": 200, "success": true } ] } ``` | Item | Regra | | - | - | | Status aceitos em `status` | `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`. Outros valores respondem `400` | | Resposta de sucesso | `201`, com `deliveries`: uma linha por destino, com `url`, `status`, `success` e, quando houver, `error` | | Só cobranças de teste | Cobrança de produção responde `403` com `Redisparo de webhook disponível apenas para cobranças de teste` | | Cobrança inexistente | `404` com `Cobrança não encontrada` | Um roteiro útil de simulação: 1. `{"status": "paid"}`: confira se o receptor responde `2xx` e se o pedido, já liberado pelo `charge.paid` real, **não** é liberado de novo. O evento simulado tem `id` novo, então quem segura a duplicidade aqui é a checagem do pedido. 2. `{"status": "refunded"}`: confira se o pedido é marcado como estornado. 3. `{"status": "refused"}` e `{"status": "failed"}`: confira se o pedido é marcado como não pago. > [!NOTE] > > O payload simulado não é idêntico ao real: traz campos a mais e não traz `anticipation_fee_estimated`. Use a simulação para testar conectividade e o tratamento de cada evento, e não como referência de formato. O formato real está em [Webhooks de cobrança](/guias/webhooks/cobranca). ## 6. Consulte a cobrança Os webhooks não têm assinatura HMAC ([Webhooks](/guias/webhooks/visao-geral#regras-de-negócio)), então confirme o estado da cobrança na API antes de uma ação crítica. A consulta também é o caminho quando o seu receptor ficou fora do ar. ```http REST (JSON) theme={null} GET /v1/charges/2vorkDcXyvzifL63YX09S9VqcnI HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "$FINVIA_API_URL/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} // consultar.mjs (Node.js 18+, ESM, await no topo) const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const chargeId = '2vorkDcXyvzifL63YX09S9VqcnI'; const response = await fetch(`${API_URL}/v1/charges/${chargeId}`, { headers: { Authorization: `Basic ${credentials}` }, }); const charge = await response.json(); if (charge.status === 'paid') { // Estado confirmado na API: pode liberar. console.log('Cobrança paga', charge.id); } ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` A resposta `200` traz o objeto completo da cobrança em camelCase: `id`, `status`, `amount`, `currency`, `spread`, `net`, `customer`, `paymentMethod`, `merchantId`, `paymentDetails`, `metadata`, `paidAt`, `createdAt` e `updatedAt`. Nas respostas de consulta, as chaves de `metadata` voltam em camelCase. Veja [Metadata](/guias/cobrancas/visao-geral#metadata). > [!WARNING] > > Para um `id` que não existe, a API responde hoje `200` com corpo vazio, sem `404`. Trate corpo vazio como "cobrança não encontrada". ## 7. Repita com cartão de crédito No cartão, a aprovação ou a recusa vem **na própria resposta** da criação. Os webhooks chegam em seguida, como complemento: `charge.paid` na aprovação, `charge.refused` (status `refused`) ou `charge.failed` (status `failed`) na recusa. O desenho abaixo mostra os dois caminhos da cobrança de cartão no tutorial, aprovada e recusada. ```mermaid placement="top-right" className="finvia-diagrama" theme={null} %%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%% sequenceDiagram autonumber box rgb(255,246,229) Comprador participant C as Comprador end box rgb(243,245,248) Sua aplicação participant S as Seu servidor participant R as Seu receptor end box rgb(234,243,255) Finvia participant F as Finvia API end C->>S: Envia os dados do cartão S->>F: POST /v1/charges (credit_card, installments) alt Aprovado (4444333322221111) F-->>S: 201 · status paid S-->>C: Pedido confirmado F-)R: charge.paid else Recusado (4444333322221112) F-->>S: 201 · status refused · reason card_declined S-->>C: Mensagem amigável e outra forma de pagamento F-)R: charge.refused ou charge.failed, sem o motivo end Note over S,F: A resposta síncrona decide o checkout. O webhook é complementar. ``` No Modo Teste, o resultado depende só do número do cartão: | Número | Resultado | | - | - | | `4444333322221111` | Aprovado (`paid`, `reason` `success`) | | `4444333322221112` | Recusado (`refused`, `reason` `card_declined`) | | Terminado em `2222` (ex.: `4444333322222222`) | Pendente (`pending`), sem confirmação posterior simulada | | Qualquer outro número | Aprovado | A tabela completa e as regras estão em [Cartões de teste](/primeiros-passos/credenciais-e-ambientes#cartões-de-teste). Use uma conta sem 3D Secure obrigatório para testar a recusa: com 3DS ou antifraude ligados, a recusa pode vir dessas etapas, com outro `reason`. ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 150, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria.souza@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2030", "cvv": "123", "installments": 3 }, "items": [ { "title": "Curso online", "type": "digital", "description": "Acesso de 12 meses", "unit_price": 150, "quantity": 1 } ], "metadata": { "orderId": "PED-1001" }, "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "$FINVIA_API_URL/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 150, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria.souza@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2030", "cvv": "123", "installments": 3 }, "items": [ { "title": "Curso online", "type": "digital", "description": "Acesso de 12 meses", "unit_price": 150, "quantity": 1 } ], "metadata": { "orderId": "PED-1001" }, "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" }' ``` ```javascript Node.js theme={null} // criar-cartao.mjs (Node.js 18+, ESM, await no topo) const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch(`${API_URL}/v1/charges`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 150, currency: 'BRL', customer: { name: 'Maria Souza', email: 'maria.souza@email.com', document: { type: 'cpf', id: '52998224725' }, phone: '+5511987654321', address: { country: 'BRA' }, }, paymentMethod: { type: 'credit_card', number: '4444333322221111', holderName: 'MARIA SOUZA', expirationMonth: '10', expirationYear: '2030', cvv: '123', installments: 3, }, items: [ { title: 'Curso online', type: 'digital', description: 'Acesso de 12 meses', unit_price: 150, quantity: 1, }, ], metadata: { orderId: 'PED-1001' }, postbackUrl: 'https://abc123.ngrok.io/webhooks/finvia', }), }); const charge = await response.json(); if (charge.status === 'paid') { // Aprovado: confirme o pedido. console.log('Aprovado', charge.id); } else if (charge.status === 'refused' || charge.status === 'failed') { // Recusado ou falhou: mostre charge.reason e ofereça outra forma de pagamento. console.log('Não aprovado', charge.reason); } ``` ```python Python theme={null} import os import requests payload = { "amount": 150, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria.souza@email.com", "document": { "type": "cpf", "id": "52998224725", }, "phone": "+5511987654321", "address": { "country": "BRA", }, }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2030", "cvv": "123", "installments": 3, }, "items": [ { "title": "Curso online", "type": "digital", "description": "Acesso de 12 meses", "unit_price": 150, "quantity": 1, }, ], "metadata": { "orderId": "PED-1001", }, "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 150, 'currency' => 'BRL', 'customer' => [ 'name' => 'Maria Souza', 'email' => 'maria.souza@email.com', 'document' => [ 'type' => 'cpf', 'id' => '52998224725', ], 'phone' => '+5511987654321', 'address' => [ 'country' => 'BRA', ], ], 'paymentMethod' => [ 'type' => 'credit_card', 'number' => '4444333322221111', 'holderName' => 'MARIA SOUZA', 'expirationMonth' => '10', 'expirationYear' => '2030', 'cvv' => '123', 'installments' => 3, ], 'items' => [ [ 'title' => 'Curso online', 'type' => 'digital', 'description' => 'Acesso de 12 meses', 'unit_price' => 150, 'quantity' => 1, ], ], 'metadata' => [ 'orderId' => 'PED-1001', ], 'postbackUrl' => 'https://abc123.ngrok.io/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 150, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria.souza@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2030", "cvv": "123", "installments": 3 }, "items": [ { "title": "Curso online", "type": "digital", "description": "Acesso de 12 meses", "unit_price": 150, "quantity": 1 } ], "metadata": { "orderId": "PED-1001" }, "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 150, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria.souza@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2030", "cvv": "123", "installments": 3 }, "items": [ { "title": "Curso online", "type": "digital", "description": "Acesso de 12 meses", "unit_price": 150, "quantity": 1 } ], "metadata": { "orderId": "PED-1001" }, "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 150, "currency": "BRL", "customer": { "name": "Maria Souza", "email": "maria.souza@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "credit_card", "number": "4444333322221111", "holderName": "MARIA SOUZA", "expirationMonth": "10", "expirationYear": "2030", "cvv": "123", "installments": 3 }, "items": [ { "title": "Curso online", "type": "digital", "description": "Acesso de 12 meses", "unit_price": 150, "quantity": 1 } ], "metadata": { "orderId": "PED-1001" }, "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 150, "currency" => "BRL", "customer" => { "name" => "Maria Souza", "email" => "maria.souza@email.com", "document" => { "type" => "cpf", "id" => "52998224725", }, "phone" => "+5511987654321", "address" => { "country" => "BRA", }, }, "paymentMethod" => { "type" => "credit_card", "number" => "4444333322221111", "holderName" => "MARIA SOUZA", "expirationMonth" => "10", "expirationYear" => "2030", "cvv" => "123", "installments" => 3, }, "items" => [ { "title" => "Curso online", "type" => "digital", "description" => "Acesso de 12 meses", "unit_price" => 150, "quantity" => 1, }, ], "metadata" => { "orderId" => "PED-1001", }, "postbackUrl" => "https://abc123.ngrok.io/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` Exemplo de resposta `201` aprovada: ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "paid", "paymentDetails": { "firstSix": "444433", "lastFour": "1111", "expirationMonth": "10", "expirationYear": "2030", "holderName": "MARIA SOUZA", "installments": 3 }, "reason": null } ``` Exemplo de resposta `201` recusada, com o cartão `4444333322221112`: ```json theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "refused", "paymentDetails": null, "reason": "card_declined" } ``` Na recusa síncrona, o `charge.refused` ou `charge.failed` sai no máximo uma vez por cobrança, para os endpoints e para a `postbackUrl`. O envelope padrão não traz o motivo: ele está no `reason` da resposta e na consulta da cobrança. | Regra do cartão | Valor | | - | - | | Parcelas (`installments`) | Obrigatório, de `1` a `12` | | Mês e ano de validade | Texto com 2 e 4 caracteres (`"10"`, `"2030"`) | | CVV | Texto, mínimo de 3 caracteres | | Número | Texto, só dígitos, sem espaços | > [!TIP] > > **Para o desenvolvedor:** para não guardar dados de cartão no seu servidor, o caminho é o [cofre de cartões](/guias/cofre-de-cartoes). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` com `"message": "Unauthorized"` | Cabeçalho ausente, chave inválida ou Base64 montado sem os dois pontos | Decodifique o Base64 e confira se termina em `:` e se o prefixo é `Basic ` | | `403` com `"message": "Acesso negado"` ao criar cobrança | O perfil do usuário que gerou a chave não pode criar cobranças (ex.: Desenvolvedor) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave) | | `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie `shippingAddress` com `postalCode`, `addressLine1`, `city`, `state` e `country` | | `422` com `Fees not configured` | A conta não tem taxa configurada para o método, a moeda ou o número de parcelas | Fale com o suporte da Finvia | | `400` com `CVV is required when using cardTokenId` | Cobrança com cartão salvo sem `cvv` | Envie o `cvv` junto com o `cardTokenId` | | `403` na rota de simulação de webhook | A cobrança não é de teste | Use uma cobrança criada com a chave `sk_test_` | | Webhook não chega | URL inacessível pela internet ou receptor respondendo com erro | Confira a URL do ngrok, se o servidor está rodando e se ele responde com status `2xx`. Qualquer outra resposta conta como falha de entrega | Mais detalhes em [Erros e como tratar](/primeiros-passos/erros). ## Perguntas frequentes > [accordion] Preciso cadastrar o cliente antes de criar a cobrança? > > Não. Ao enviar `name` e `email` (ou `phone`) dentro de `customer`, a API cria ou localiza o cliente na mesma chamada. O cadastro prévio com `POST /v1/customers` é útil quando o cliente volta a comprar, guarda cartão ou assina um plano: aí basta enviar o `customer.id`. > [accordion] Posso usar só a postbackUrl, sem cadastrar webhook no painel? > > Pode, para eventos de cobrança. Os eventos que cada canal recebe estão na [tabela de eventos por canal](/guias/webhooks/visao-geral#eventos-por-canal). Os eventos de assinatura chegam só aos endpoints cadastrados no painel. > [accordion] Se eu já tenho o status na resposta do cartão, preciso do webhook? > > Sim. A resposta resolve o checkout, e os eventos posteriores, como estorno, alerta de contestação e bloqueio, só chegam por notificação. > [accordion] Como sei que a cobrança veio do sandbox? > > No webhook, `livemode` vem `false` e `data.is_test` vem `true`. No `charge.updated` legado, o indicador é `data.isTest`. Os mesmos endpoints recebem eventos de teste e de produção, então descarte ou separe os eventos com `livemode: false` no ambiente de produção. > [accordion] A requisição deu timeout. Posso criar a cobrança de novo? > > Não reenvie às cegas: a API não aceita `Idempotency-Key`. Veja a estratégia segura em [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia). ## Checklist do que você terá ao final * [ ] Chave de teste guardada em variável de ambiente, nunca no código. * [ ] `GET /v1/payment-methods` respondendo `200`. * [ ] Receptor de webhooks em HTTPS respondendo `2xx` rapidamente. * [ ] Cobrança Pix criada, com `id` guardado junto ao pedido. * [ ] QR Code exibido a partir de `qrCodeBase64`, com `copyPaste` como alternativa. * [ ] `charge.created` e `charge.pending` recebidos na `postbackUrl`. * [ ] `charge.paid` recebido cerca de 5 segundos depois, com o mesmo `id` da criação. * [ ] Eventos de teste reconhecidos por `livemode: false`. * [ ] Outros status simulados com `POST /v1/charges/{id}/resend-webhook`, sem liberar o pedido duas vezes. * [ ] Estado confirmado com `GET /v1/charges/{id}` antes de liberar o pedido. * [ ] Cobranças de cartão aprovada (`4444333322221111`) e recusada (`4444333322221112`), com tratamento de `paid`, `refused` e `failed` na resposta. ## Como testar Este tutorial cobre a base dos cenários **CHG-01** (cartão aprovado), **CHG-02** (cartão parcelado), **CHG-03** (cartão recusado, com o cartão `4444333322221112`), **CHG-04** (Pix gerado), **CHG-05** (Pix pago no sandbox), **CHG-06** (consulta), **CHG-08** (recebimento de webhook) e **CHG-09** (simulação de webhook) do [roteiro de homologação](/homologacao/roteiro). Guarde, para cada um, a requisição, a resposta, o `id` e o log do webhook com o status HTTP que o seu receptor devolveu. ## Veja também > [card] [Pix](/guias/cobrancas/pix) > > Regras de validade, QR Code e boas práticas do Pix. > [card] [Cartão de crédito](/guias/cobrancas/cartao-de-credito) > > Parcelamento, recusas e 3D Secure. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Todos os campos e eventos de cobrança. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Referência completa de `POST /v1/charges`. # Cancelar autenticação 3DS Source: https://docs.fastpaybrasil.com/referencia/3d-secure/cancelar POST /v1/three-ds/cancel Cancela uma autenticação 3D Secure que ainda espera envio ou desafio, quando o comprador desiste ou troca de cartão. Esta rota encerra uma autenticação 3DS que ficou pela metade. Use quando o comprador fecha o desafio do banco, volta para trocar de cartão ou desiste da compra. Cancelar deixa claro que aquela autenticação não será usada e evita confusão entre tentativas. ## Quando usar | Situação | Como usar esta rota | | - | - | | Comprador fechou a janela do desafio | Cancele o `authenticationId` e permita uma nova tentativa | | Comprador voltou para trocar de cartão | Cancele a autenticação do cartão anterior antes de iniciar a do novo | | Seu checkout atingiu o tempo limite do desafio (o SDK usa cerca de 10 minutos) | Cancele e mostre uma mensagem de nova tentativa | | A autenticação já terminou (`succeeded`, `failed`) | Esta rota não se aplica. Só cancela autenticações em `requires_submission` ou `requires_challenge` | ## Antes de chamar * Tenha o `authenticationId` devolvido por [`POST /v1/three-ds/authenticate`](/referencia/3d-secure/iniciar). * A autenticação precisa estar em `requires_submission` ou `requires_challenge`. * Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) no cabeçalho Basic, como usuário e com senha vazia. > [!NOTE] > > O contrato desta rota declara a autenticação `basic` e diz, na descrição da rota, que a chave usada é a pública (`pk_`). A descrição genérica do esquema `basic` no contrato fala em chave secreta. Siga a descrição da rota: chave pública. ## Corpo da requisição **authenticationId** `string` *required* ID da autenticação 3DS a cancelar, exatamente como veio em `POST /v1/three-ds/authenticate`. O valor é opaco: não valide prefixo nem tamanho. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. ## Respostas **authenticationId** `string` ID da autenticação cancelada. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. **status** `string` Status da autenticação depois do cancelamento. Ex.: `canceled`. | HTTP | Significado | Mensagem (`message`) | | - | - | - | | `200` | Autenticação cancelada | | | `401` | Chave pública inválida | `Unauthorized` | | `404` | Nenhum provedor de 3DS configurado para a conta | `No 3DS provider configured for this gateway` | Os erros vêm no formato `{ statusCode, message, error }`. Trate o erro pelo código HTTP, não pelo texto da mensagem. > [!NOTE] > > O contrato não documenta a resposta para o cancelamento de uma autenticação que já está em estado final (por exemplo, `succeeded`). Chame esta rota só nos estados `requires_submission` e `requires_challenge`. > [!NOTE] > > **Para o negócio:** cancelar uma autenticação não cria nem cancela cobrança. A cobrança só existe depois de `POST /v1/charges`. Se o comprador desistiu antes disso, nada foi cobrado. ## Exemplo: comprador fechou o desafio ```javascript theme={null} const credentials = btoa(`${FINVIA_PUBLIC_KEY}:`); async function aoFecharDesafio(authenticationId) { await fetch('https://api-global.fastpaybrasil.com/v1/three-ds/cancel', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ authenticationId }), }); mostrarMensagem('Autenticação cancelada. Tente de novo ou use outro cartão.'); } ``` > [!TIP] > > **Para o desenvolvedor:** para uma nova tentativa depois do cancelamento, inicie uma nova autenticação em [`POST /v1/three-ds/authenticate`](/referencia/3d-secure/iniciar). Use o novo `authenticationId` devolvido por ela nas etapas seguintes. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `No 3DS provider configured for this gateway` | A conta não tem provedor de 3DS configurado | Fale com o time Finvia para habilitar o 3DS | | `401` `Unauthorized` | Chave pública inválida ou de outro ambiente | Use a `pk_` (ou `pk_test_`) da conta que iniciou a autenticação | ```http REST (JSON) theme={null} POST /v1/three-ds/cancel HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/cancel" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X" }' ``` ```javascript Navegador theme={null} const credentials = btoa(`${FINVIA_PUBLIC_KEY}:`); const response = await fetch('https://api-global.fastpaybrasil.com/v1/three-ds/cancel', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ authenticationId: 'tdsa_1QmCRMJM0r9zBvr4OVmMRa6X' }), }); const result = await response.json(); ``` ```json 200 theme={null} { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "canceled" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "No 3DS provider configured for this gateway", "error": "Not Found" } ``` ## Veja também > [card] [Iniciar autenticação](/referencia/3d-secure/iniciar) > > Comece uma nova tentativa. > [card] [Enviar autenticação](/referencia/3d-secure/enviar) > > Etapa anterior ao desafio. > [card] [3DS via API](/guias/3d-secure/via-api) > > Guia do fluxo completo. > [card] [Visão geral do 3D Secure](/guias/3d-secure/visao-geral) > > Os três caminhos de 3DS. # Enviar autenticação 3DS Source: https://docs.fastpaybrasil.com/referencia/3d-secure/enviar POST /v1/three-ds/submit Envia a autenticação 3DS ao banco depois da coleta de dados do navegador e devolve o novo status, com a URL do desafio quando o banco pedir. Depois de iniciar a autenticação e, se pedido, coletar os dados do dispositivo (fingerprinting), esta rota envia a autenticação para o banco emissor decidir. A resposta diz se o banco aprovou sem interação, se ele quer um desafio do comprador ou se a autenticação falhou. É a segunda chamada do **3DS via API**. A primeira é [Iniciar autenticação](/referencia/3d-secure/iniciar). ## Quando usar | Situação | O que enviar | | - | - | | A inicialização trouxe `fingerprintingUrl` e o iframe devolveu o resultado | `authenticationId` e `fingerprintingResult` | | A inicialização veio com `status` `requires_submission`, sem `fingerprintingUrl` | Só o `authenticationId` | | A inicialização já veio com `requires_challenge` | Não precisa desta rota. Mostre o desafio e vá para [resultado do desafio](/referencia/3d-secure/resultado-desafio) | ## Antes de chamar * Tenha o `authenticationId` devolvido por [`POST /v1/three-ds/authenticate`](/referencia/3d-secure/iniciar). * Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) no cabeçalho Basic, como usuário e com senha vazia. * Se houve fingerprinting, espere a mensagem de fim do iframe oculto (ou o tempo limite de cerca de 60 segundos) antes de chamar. > [!NOTE] > > O contrato desta rota declara a autenticação `basic` e diz, na descrição da rota, que a chave usada é a pública (`pk_`). A descrição genérica do esquema `basic` no contrato fala em chave secreta. Siga a descrição da rota: chave pública. ## Corpo da requisição **authenticationId** `string` *required* ID da autenticação 3DS devolvido por `POST /v1/three-ds/authenticate`. Trate como texto opaco e repasse exatamente o valor recebido. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. **fingerprintingResult** `string` Resultado do fingerprinting em Base64, recebido pelo `postMessage` do iframe oculto. Omita se não houve etapa de fingerprinting. Ex.: `VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==`. ## Respostas **authenticationId** `string` ID da autenticação 3DS. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. **status** `string` Status da autenticação depois do envio: `requires_challenge`, `succeeded`, `failed`, `error` ou `processing`. Ex.: `requires_challenge`. **challengeUrl** `string | null` URL do desafio. Carregue em um iframe visível quando o `status` for `requires_challenge`. Ex.: `https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. **outcome** `string | null` Resultado da autenticação. Só vem preenchido em estados finais. Ex.: `authenticated`. | `status` | Próximo passo | | - | - | | `requires_challenge` | Mostre `challengeUrl` em iframe visível. Quando chegar a mensagem `3ds-authentication-challenge-complete`, chame [resultado do desafio](/referencia/3d-secure/resultado-desafio) | | `succeeded` | Banco aprovou sem desafio (frictionless). Chame [resultado do desafio](/referencia/3d-secure/resultado-desafio) para obter o criptograma e criar a cobrança | | `processing` | A autenticação ainda está em processamento | | `failed` / `error` | Estado final. Não crie a cobrança autenticada. Ofereça nova tentativa ou outro meio de pagamento | > [!NOTE] > > **Para o negócio:** a resposta desta rota decide se o comprador vai ver uma tela do banco. Com `succeeded`, o pagamento segue sem interação extra. Com `requires_challenge`, o checkout precisa mostrar o desafio do banco emissor e esperar o comprador concluir. | HTTP | Significado | Mensagem (`message`) | | - | - | - | | `200` | Autenticação enviada | | | `401` | Chave pública inválida | `Unauthorized` | | `404` | Nenhum provedor de 3DS configurado para a conta | `No 3DS provider configured for this gateway` | Os erros vêm no formato `{ statusCode, message, error }`. Trate o erro pelo código HTTP, não pelo texto da mensagem. ## Capturar o resultado do fingerprinting A página carregada no iframe oculto avisa o fim da coleta com uma mensagem `postMessage` neste formato: ```json theme={null} { "type": "3ds-authentication-fingerprinting-complete", "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==" } ``` Registre o listener antes de carregar o iframe e aceite só mensagens que venham desse iframe e tenham o `type` esperado. Se a mensagem não chegar em cerca de 60 segundos (o padrão do SDK), siga sem o resultado: `fingerprintingResult` é opcional. ```javascript theme={null} function coletarFingerprint(fingerprintingUrl, tempoLimiteMs = 60000) { return new Promise((resolve) => { const iframe = document.createElement('iframe'); iframe.style.display = 'none'; function finalizar(resultado) { window.removeEventListener('message', onMessage); clearTimeout(timer); iframe.remove(); resolve(resultado); } function onMessage(event) { if (event.source !== iframe.contentWindow) return; if (event.data?.type !== '3ds-authentication-fingerprinting-complete') return; finalizar(event.data.fingerprintingResult); } window.addEventListener('message', onMessage); const timer = setTimeout(() => finalizar(undefined), tempoLimiteMs); iframe.src = fingerprintingUrl; document.body.appendChild(iframe); }); } ``` > [!TIP] > > **Para o desenvolvedor:** a mensagem vem da página do provedor de 3DS, o host da `fingerprintingUrl`. Esse host pode mudar: valide `event.source` e `event.data.type` e não fixe um domínio em `event.origin`. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `No 3DS provider configured for this gateway` | A conta não tem provedor de 3DS configurado | Fale com o time Finvia para habilitar o 3DS | | `401` `Unauthorized` | Chave pública inválida ou de outro ambiente | Use a `pk_` (ou `pk_test_`) da conta que iniciou a autenticação | | `status` `failed` logo após o envio | O banco recusou a autenticação | Ofereça outra forma de pagamento ou outro cartão | | Checkout parado esperando o fingerprinting | Listener registrado depois do iframe, filtro pelo `type` errado, ou iframe bloqueado | Registre o listener antes, filtre por `3ds-authentication-fingerprinting-complete` e use um tempo limite de cerca de 60 segundos | ```http REST (JSON) theme={null} POST /v1/three-ds/submit HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/submit" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==" }' ``` ```javascript Navegador theme={null} const credentials = btoa(`${FINVIA_PUBLIC_KEY}:`); const fingerprintingResult = auth.fingerprintingUrl ? await coletarFingerprint(auth.fingerprintingUrl) : undefined; const response = await fetch('https://api-global.fastpaybrasil.com/v1/three-ds/submit', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ authenticationId: auth.authenticationId, fingerprintingResult }), }); const submit = await response.json(); if (submit.status === 'requires_challenge') { // Carregue submit.challengeUrl em um iframe visível } ``` ```json 200 Desafio theme={null} { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "requires_challenge", "challengeUrl": "https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "outcome": null } ``` ```json 200 Sem desafio theme={null} { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "succeeded", "challengeUrl": null, "outcome": "authenticated" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "No 3DS provider configured for this gateway", "error": "Not Found" } ``` ## Veja também > [card] [Iniciar autenticação](/referencia/3d-secure/iniciar) > > Primeiro passo do 3DS via API. > [card] [Resultado do desafio](/referencia/3d-secure/resultado-desafio) > > Dados para criar a cobrança autenticada. > [card] [Cancelar autenticação](/referencia/3d-secure/cancelar) > > Quando o comprador desiste no meio do fluxo. > [card] [3DS via API](/guias/3d-secure/via-api) > > Guia do fluxo completo. # Iniciar autenticação 3DS Source: https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar POST /v1/three-ds/authenticate Cria uma autenticação 3D Secure para um cartão e devolve o primeiro passo: coleta de dados do navegador ou desafio do banco. O 3D Secure (3DS) é a verificação em que o banco emissor do cartão confirma que quem está comprando é o titular. Esta rota abre essa verificação: você envia o valor, o cartão e os dados do navegador, e a Finvia devolve um `authenticationId` e o próximo passo. Às vezes o banco aprova sem interagir com o comprador (fluxo sem atrito, ou frictionless). Outras vezes ele pede um desafio: o comprador se autentica diretamente no banco emissor, em uma tela exibida dentro do seu checkout. Esta é a primeira chamada do **3DS via API**, o fluxo em que você conduz cada etapa. Se prefere que a Finvia conduza tudo, use o [3DS gerenciado](/guias/3d-secure/gerenciado). Se usa o SDK de segurança, ele faz estas chamadas por você ([SDK de 3D Secure](/guias/3d-secure/sdk)). ## Quando usar | Situação | Caminho | | - | - | | Você quer controlar cada etapa do 3DS no seu front-end | Esta rota, seguida de [enviar](/referencia/3d-secure/enviar) e [resultado do desafio](/referencia/3d-secure/resultado-desafio) | | Você quer o fluxo pronto no navegador, com modal | [SDK de 3D Secure](/guias/3d-secure/sdk) | | Você quer que a Finvia conduza a autenticação a partir da cobrança | `threeDSMode` `managed` em [`POST /v1/charges`](/referencia/cobrancas/criar) | | Pagamento com Apple Pay | Não se aplica: a autenticação já vem no token do Apple Pay | > [!NOTE] > > **Para o negócio:** quando a configuração da sua conta exige 3DS, uma cobrança de cartão sem autenticação bem-sucedida é recusada. O 3DS acrescenta uma etapa ao checkout e, em alguns casos, um desafio para o comprador. Decida com o time técnico qual dos três caminhos (gerenciado, SDK ou via API) combina com o seu checkout. ## Antes de chamar * Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) no cabeçalho Basic, como usuário e com senha vazia. Esta rota foi feita para ser chamada do navegador, onde a chave secreta nunca pode aparecer. * A conta precisa ter um provedor de 3DS configurado. Sem ele, a rota responde `404` com a mensagem `No 3DS provider configured for this gateway`. * Colete os dados do navegador do comprador (objeto `browser`). ```text theme={null} Authorization: Basic base64(pk_sua_chave_publica:) ``` > [!WARNING] > > Nunca use a chave secreta (`sk_`) no front-end. As rotas de 3D Secure usam a chave pública. > [!NOTE] > > O contrato desta rota declara a autenticação `basic` e diz, na descrição da rota, que a chave usada é a pública (`pk_`) como usuário do Basic. A descrição genérica do esquema `basic` no contrato fala em chave secreta. Siga a descrição da rota: chave pública. ## Corpo da requisição Campos obrigatórios: `amount`, `currency`, `card` e `browser`. **amount** `number` *required* Valor da transação na moeda informada, em reais quando a moeda é `BRL`. Ex.: `100`. **currency** `string` *required* Código da moeda no padrão ISO 4217. Ex.: `BRL`. **card** `object` *required* Cartão que será autenticado. **propriedades** **number** `string` *required* Número do cartão. Ex.: `4111111111111111`. **holderName** `string` Nome do titular. Ex.: `John Doe`. **expirationMonth** `string` *required* Mês de validade, de 1 a 12, com 1 ou 2 dígitos. Ex.: `12`. **expirationYear** `string` *required* Ano de validade com 4 dígitos. Ex.: `2025`. **browser** `object` *required* Dados do navegador do comprador, usados pelo banco na análise (schema `BrowserInfo`). **propriedades** **userAgent** `string` *required* User agent do navegador. Ex.: `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`. **ipAddress** `string` *required* IP do comprador. Ex.: `177.128.144.97`. **acceptHeader** `string` Valor do cabeçalho Accept do navegador. Ex.: `text/html,application/xhtml+xml`. **language** `string` Idioma do navegador. Ex.: `pt-BR`. **timezoneOffset** `integer` Diferença do fuso em minutos em relação ao UTC. Ex.: `-180`. **javascriptEnabled** `boolean` Se o JavaScript está habilitado. Ex.: `true`. **javaEnabled** `boolean` Se o Java está habilitado. Ex.: `false`. **screenWidth** `integer` Largura da tela em pixels. Ex.: `1920`. **screenHeight** `integer` Altura da tela em pixels. Ex.: `1080`. **colorDepth** `integer` Profundidade de cor da tela, em bits. Ex.: `24`. > [!TIP] > > **Para o desenvolvedor:** quase todos os campos de `browser` saem direto do JavaScript da página: `navigator.userAgent`, `navigator.language`, `screen.width`, `screen.height` e `screen.colorDepth`. Para `timezoneOffset`, inverta o sinal de `new Date().getTimezoneOffset()`: no horário de Brasília ele devolve `180`, e o exemplo do contrato é `-180`. O `ipAddress` precisa vir do seu servidor, que enxerga o IP de quem fez a requisição. ## Respostas **authenticationId** `string` Identificador da autenticação 3DS. Guarde: ele é enviado em [enviar](/referencia/3d-secure/enviar), [cancelar](/referencia/3d-secure/cancelar) e [resultado do desafio](/referencia/3d-secure/resultado-desafio). O valor é gerado pelo provedor de 3DS e deve ser tratado como texto opaco: repasse exatamente o que recebeu, sem validar prefixo nem tamanho. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. **status** `string` Situação atual da autenticação: `requires_submission`, `requires_challenge`, `succeeded`, `failed`, `error`, `canceled` ou `processing`. Ex.: `requires_submission`. **fingerprintingUrl** `string | null` URL para carregar em um iframe **oculto**, que coleta dados do dispositivo (fingerprinting). Ao terminar, a página envia por `postMessage` a mensagem `{ "type": "3ds-authentication-fingerprinting-complete", "fingerprintingResult": "" }`. Depois chame [`POST /v1/three-ds/submit`](/referencia/3d-secure/enviar). Ex.: `https://provedor-3ds.exemplo.com/fingerprint/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. **challengeUrl** `string | null` URL para carregar em um iframe **visível** quando o `status` é `requires_challenge`. É nesse iframe que o comprador faz o desafio do banco. Ao final, a página envia por `postMessage` a mensagem `{ "type": "3ds-authentication-challenge-complete", "status": "succeeded" }` (ou `failed`, `error`, `canceled`). Ex.: `https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. **outcome** `string | null` Resultado da autenticação. Só vem preenchido em estados finais. Valores: `authenticated`, `informational`, `attempt_acknowledged`, `rejected`, `denied`, `abandoned`, `not_supported`, `processing_error`, `internal_error`, `canceled`. Ex.: `authenticated`. > [!NOTE] > > As URLs de `fingerprintingUrl` e `challengeUrl` são da página do provedor de 3DS, e o host pode mudar. Não fixe o domínio no código. Ao receber uma mensagem, confira se `event.source === iframe.contentWindow` e se `event.data.type` é o tipo esperado. O fluxo completo, com exemplos, está no guia [3DS via API](/guias/3d-secure/via-api). ### O que fazer com cada status | `status` | Próximo passo | | - | - | | `requires_submission` | Se veio `fingerprintingUrl`, carregue em iframe oculto e espere a mensagem de fim, por cerca de 60 segundos. Depois chame [enviar](/referencia/3d-secure/enviar), com `fingerprintingResult` se ele chegou e sem ele se não chegou. Sem `fingerprintingUrl`, chame enviar direto | | `requires_challenge` | Carregue `challengeUrl` em iframe visível. Depois da mensagem de fim do desafio, chame [resultado do desafio](/referencia/3d-secure/resultado-desafio) | | `processing` | A autenticação ainda está em processamento | | `succeeded` | Autenticação concluída. Busque o resultado em [resultado do desafio](/referencia/3d-secure/resultado-desafio) para criar a cobrança | | `failed` / `error` | Estado final. Chame [resultado do desafio](/referencia/3d-secure/resultado-desafio) para obter o `state` e não siga com a cobrança autenticada | | `canceled` | A autenticação foi cancelada | | HTTP | Significado | Mensagem (`message`) | | - | - | - | | `200` | Autenticação iniciada | | | `401` | Chave pública inválida | `Unauthorized` | | `404` | Nenhum provedor de 3DS configurado para a conta | `No 3DS provider configured for this gateway` | Trate o erro pelo código HTTP, não pelo texto da mensagem. O corpo de erro tem três campos: **statusCode** `integer` Código HTTP. **message** `string` Mensagem descritiva do erro. **error** `string` Tipo do erro. ## Fluxo completo do 3DS via API **1. Inicie a autenticação** Chame esta rota com o cartão, o valor e os dados do navegador. Guarde o `authenticationId`. **2. Faça o fingerprinting, se pedido** Se a resposta trouxer `fingerprintingUrl`, carregue a URL em um iframe oculto e espere a mensagem `3ds-authentication-fingerprinting-complete`, com o `fingerprintingResult`. **3. Envie a autenticação** Chame [`POST /v1/three-ds/submit`](/referencia/3d-secure/enviar) com o `authenticationId` e, se houver, o `fingerprintingResult`. **4. Mostre o desafio, se pedido** Se o `status` for `requires_challenge`, carregue `challengeUrl` em um iframe visível para o comprador concluir o desafio e espere a mensagem `3ds-authentication-challenge-complete`. **5. Busque o resultado** Chame [`POST /v1/three-ds/challenge-result`](/referencia/3d-secure/resultado-desafio) depois do fim do desafio, ou quando a autenticação já estiver em estado final. A resposta traz o criptograma e os identificadores da autenticação. **6. Crie a cobrança** Envie o resultado no campo `paymentMethod.threeDS` de [`POST /v1/charges`](/referencia/cobrancas/criar), chamado do seu servidor com a chave secreta. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `No 3DS provider configured for this gateway` | A conta não tem provedor de 3DS configurado | Fale com o time Finvia para habilitar o 3DS | | `401` `Unauthorized` | Chave pública inválida, de outro ambiente, ou chave secreta no lugar | Use a `pk_` (ou `pk_test_`) da conta | | Chave secreta exposta no navegador | A chamada foi feita com `sk_` no front-end | Troque pela chave `pk_` e gere uma nova chave secreta | | Iframe de fingerprinting não devolve nada | Listener de `postMessage` não registrado antes de carregar o iframe | Registre o listener e só depois carregue a `fingerprintingUrl` | ```http REST (JSON) theme={null} POST /v1/three-ds/authenticate HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 100, "currency": "BRL", "card": { "number": "4111111111111111", "holderName": "Joao Silva", "expirationMonth": "12", "expirationYear": "2025" }, "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/authenticate" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "BRL", "card": { "number": "4111111111111111", "holderName": "Joao Silva", "expirationMonth": "12", "expirationYear": "2025" }, "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "ipAddress": "177.128.144.97", "acceptHeader": "text/html,application/xhtml+xml", "language": "pt-BR", "timezoneOffset": -180, "javascriptEnabled": true, "javaEnabled": false, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24 } }' ``` ```javascript Navegador theme={null} // Chave pública: pode ficar no front-end const credentials = btoa(`${FINVIA_PUBLIC_KEY}:`); const response = await fetch('https://api-global.fastpaybrasil.com/v1/three-ds/authenticate', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 100, currency: 'BRL', card: { number: cardNumber, holderName, expirationMonth: '12', expirationYear: '2025' }, browser: { userAgent: navigator.userAgent, ipAddress: ipDoComprador, // obtido pelo seu servidor language: navigator.language, timezoneOffset: -new Date().getTimezoneOffset(), javascriptEnabled: true, javaEnabled: false, screenWidth: screen.width, screenHeight: screen.height, colorDepth: screen.colorDepth, }, }), }); const auth = await response.json(); ``` ```json 200 Fingerprinting theme={null} { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "requires_submission", "fingerprintingUrl": "https://provedor-3ds.exemplo.com/fingerprint/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "challengeUrl": null, "outcome": null } ``` ```json 200 Desafio theme={null} { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "requires_challenge", "fingerprintingUrl": null, "challengeUrl": "https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "outcome": null } ``` ```json 404 theme={null} { "statusCode": 404, "message": "No 3DS provider configured for this gateway", "error": "Not Found" } ``` ## Veja também > [card] [3DS via API](/guias/3d-secure/via-api) > > Guia do fluxo completo com as rotas de 3DS. > [card] [Enviar autenticação](/referencia/3d-secure/enviar) > > Próximo passo depois do fingerprinting. > [card] [Visão geral do 3D Secure](/guias/3d-secure/visao-geral) > > Gerenciado, SDK ou via API. > [card] [SDK de 3D Secure](/guias/3d-secure/sdk) > > O mesmo fluxo com o SDK no navegador. # Obter resultado do 3DS Source: https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio POST /v1/three-ds/challenge-result Devolve o resultado final da autenticação 3D Secure, com o criptograma e os identificadores que vão na cobrança de cartão. Quando a autenticação 3DS termina, esta rota entrega o que a cobrança precisa para provar que o comprador foi autenticado: o estado final, o criptograma (CAVV), o ECI, a versão do protocolo e os identificadores da transação no banco e na bandeira. Esse conjunto vai no campo `paymentMethod.threeDS` de [`POST /v1/charges`](/referencia/cobrancas/criar). É a última chamada do **3DS via API**, antes da criação da cobrança. ## Quando usar | Situação | Como usar esta rota | | - | - | | O comprador concluiu o desafio do banco | Chame com o `authenticationId` e use a resposta na cobrança | | O envio voltou `succeeded` (sem desafio) | Chame para obter o criptograma e os identificadores | | 3DS gerenciado (`threeDSMode` `managed`) | Não precisa chamar. A página de autenticação chama esta rota e [Retomar cobrança após 3DS](/referencia/3d-secure/retomar-cobranca) | | Uso do SDK de 3D Secure | O método `process()` do SDK já chama esta rota e devolve um objeto com estes campos | ## Antes de chamar * Tenha o `authenticationId` devolvido por [`POST /v1/three-ds/authenticate`](/referencia/3d-secure/iniciar). * Chame só depois da mensagem de fim do desafio (`3ds-authentication-challenge-complete`), ou quando `authenticate` ou `submit` já devolveram um status final (`succeeded`, `failed`, `error` ou `canceled`). Antes disso, a rota responde `500` com a mensagem `Authentication challenge not yet completed...` ou devolve `state` `error`. * Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) no cabeçalho Basic, como usuário e com senha vazia. > [!NOTE] > > O contrato desta rota declara a autenticação `basic` e diz, na descrição da rota, que a chave usada é a pública (`pk_`). A descrição genérica do esquema `basic` no contrato fala em chave secreta. Siga a descrição da rota: chave pública. ## Corpo da requisição **authenticationId** `string` *required* ID da autenticação 3DS devolvido por `POST /v1/three-ds/authenticate`. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`. > [!NOTE] > > O `authenticationId` é gerado pelo provedor de 3DS e deve ser tratado como texto opaco. Repasse exatamente o valor recebido em `POST /v1/three-ds/authenticate`, sem validar prefixo nem tamanho. ## Respostas A resposta `200` é o resultado final do desafio (schema `ThreeDSChallengeResult`). Os campos `type` e `state` vêm sempre. Os demais nunca vêm `null`: quando o provedor não devolve um valor, o campo fica ausente da resposta. **type** `string` Tipo de autenticação 3DS. Hoje vem sempre `full`. Ex.: `full`. **state** `string` Estado da autenticação: `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled`. Ex.: `success`. **cryptogram** `string` CAVV, o valor de autenticação gerado pelo banco. Ausente quando não houver valor. Ex.: `Vt5xwasruB0Q6qRoG9mpzdRPqQs=`. **directoryServerTransactionId** `string` ID da transação no Directory Server (bandeira). Ex.: `607bb317-8d24-45a7-a3c0-7ae1fdca56d0`. **threeDsServerTransactionId** `string` ID da transação no 3DS Server. Ex.: `59588a8b-955e-4aa8-bae1-338bbfdba8fa`. **acsTransactionId** `string` ID da transação no ACS (banco emissor). Ex.: `6bf18a7a-3a7b-488f-bce1-3da96c73e746`. **eci** `string` Electronic Commerce Indicator. Ex.: `05`. **version** `string` Versão do protocolo 3DS. Ex.: `2.2.0`. ### O que fazer com cada `state` | `state` | Significado | Ação sugerida | | - | - | - | | `success` | Autenticação bem-sucedida | Criar a cobrança com o resultado em `paymentMethod.threeDS` | | `failure` | O comprador não passou na autenticação | Recusar a tentativa ou pedir outro meio de pagamento | | `unenrolled` | Cartão não inscrito no 3DS | Decidir conforme a sua política de risco | | `error` | Erro no processo de autenticação | Tentar de novo ou usar outro meio | | `unsupported_brand` | A bandeira não suporta 3DS | Usar outro meio de pagamento | | `disabled` | 3DS desabilitado para este cartão | Decidir conforme a sua política de risco | > [!WARNING] > > Quando a configuração da sua conta exige 3DS, só `state` `success` permite que a cobrança siga. Uma cobrança enviada com outro estado é recusada, com o motivo em `reason` (por exemplo, `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card`). Quando o 3DS não é obrigatório para a conta, os dados 3DS são repassados sem essa validação. > [!NOTE] > > **Para o negócio:** `unenrolled` e `disabled` são casos em que o banco não autenticou, mas também não recusou. O que fazer nesses casos é uma decisão de risco da sua empresa. Combine a regra com a área responsável antes de liberar o checkout. | HTTP | Significado | Mensagem (`message`) | | - | - | - | | `200` | Resultado obtido | | | `401` | Chave pública inválida | `Unauthorized` | | `404` | Nenhum provedor de 3DS configurado para a conta | `No 3DS provider configured for this gateway` | | `500` | A rota foi chamada antes do fim do desafio | `Authentication challenge not yet completed...` | Os erros vêm no formato `{ statusCode, message, error }`. Trate o erro pelo código HTTP, não pelo texto da mensagem. ## Usar o resultado na cobrança O resultado é obtido no navegador, com a chave pública. A cobrança é criada no **seu servidor**, com a chave secreta. Envie o resultado do front-end para o seu servidor e inclua-o em `paymentMethod.threeDS`: ```json theme={null} { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" } }, "paymentMethod": { "type": "credit_card", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", "installments": 1, "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746" } }, "items": [ { "title": "Curso online", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 100, "quantity": 1 } ] } ``` > [!TIP] > > **Para o desenvolvedor:** repasse a resposta desta rota do jeito que veio, sem alterar valores e sem acrescentar campos. No objeto `threeDS` da cobrança, `type` e `state` são obrigatórios; com `state` `success`, `cryptogram` e `eci` são, na prática, obrigatórios. Nos campos opcionais, omita o campo quando não tiver valor e nunca envie `null`: o `null` é gravado e repassado ao adquirente, e alguns adquirentes recusam. Com 3DS obrigatório, `cryptogram` ou `eci` nulos fazem a cobrança ser recusada com `3ds_incomplete`. Use o mesmo cartão e o mesmo valor da autenticação. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `No 3DS provider configured for this gateway` | A conta não tem provedor de 3DS configurado | Fale com o time Finvia para habilitar o 3DS | | `500` `Authentication challenge not yet completed...` ou `state` `error` | A rota foi chamada antes do fim do desafio | Espere a mensagem `3ds-authentication-challenge-complete` antes de chamar | | Cobrança recusada com `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | A conta exige 3DS e a cobrança foi enviada sem `threeDS` | Inclua o resultado desta rota em `paymentMethod.threeDS` | | Cobrança recusada com `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` | `cryptogram` ou `eci` ausentes ou nulos na cobrança | Repasse a resposta completa desta rota, sem trocar campos por `null` | | Cobrança recusada com `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card` | O comprador não passou na autenticação | Peça nova tentativa ou outro meio de pagamento | ```http REST (JSON) theme={null} POST /v1/three-ds/challenge-result HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/challenge-result" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X" }' ``` ```javascript Navegador theme={null} const credentials = btoa(`${FINVIA_PUBLIC_KEY}:`); const response = await fetch('https://api-global.fastpaybrasil.com/v1/three-ds/challenge-result', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ authenticationId: auth.authenticationId }), }); const threeDS = await response.json(); if (threeDS.state === 'success') { // Envie threeDS ao seu servidor, que cria a cobrança com a chave secreta await fetch('/api/pedidos/finalizar', { method: 'POST', body: JSON.stringify({ threeDS }) }); } ``` ```json 200 theme={null} { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746", "eci": "05", "version": "2.2.0" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "No 3DS provider configured for this gateway", "error": "Not Found" } ``` ## Veja também > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Campo `paymentMethod.threeDS`. > [card] [Retomar cobrança após 3DS](/referencia/3d-secure/retomar-cobranca) > > Continuação do 3DS gerenciado. > [card] [3DS via API](/guias/3d-secure/via-api) > > Guia do fluxo completo. > [card] [SDK de 3D Secure](/guias/3d-secure/sdk) > > O mesmo resultado obtido pelo SDK. # Retomar cobrança após 3DS Source: https://docs.fastpaybrasil.com/referencia/3d-secure/retomar-cobranca POST /v1/charges/{id}/resume-3ds Conclui uma cobrança criada com 3DS gerenciado: recebe o resultado da autenticação e processa o pagamento. No **3DS gerenciado**, a cobrança de cartão é criada com `threeDSMode` `managed` e, quando o banco pede verificação ou desafio, fica no status `authentication_required` até o comprador se autenticar. Esta rota é a continuação: ela recebe o resultado da autenticação, processa a cobrança e dispara os webhooks e o postback. A resposta tem o mesmo formato da resposta de criação de cobrança. Quem chama esta rota é a página de autenticação aberta pela `authenticationUrl`, depois que o comprador conclui a verificação. No fluxo gerenciado, a sua integração não precisa chamá-la: ela cria a cobrança, abre a `authenticationUrl` e acompanha o resultado por webhook ou por `GET /v1/charges/{id}`. Veja o [guia do 3DS gerenciado](/guias/3d-secure/gerenciado). ## Quando usar | Situação | Caminho | | - | - | | Fluxo gerenciado padrão, com a `authenticationUrl` aberta para o comprador | A página de autenticação chama esta rota. Você só acompanha o resultado | | Cobrança criada sem `threeDSMode` | Não se aplica. Para 3DS feito por você, envie `paymentMethod.threeDS` já na criação | | Cobrança em qualquer status diferente de `authentication_required` | A rota responde `404` | > [!NOTE] > > **Para o negócio:** no 3DS gerenciado, a cobrança existe desde o início, mas só é processada quando esta rota é chamada com o resultado da autenticação. Enquanto ela estiver em `authentication_required`, o pedido não está pago. ## Antes de chamar * A cobrança precisa ter sido criada em [`POST /v1/charges`](/referencia/cobrancas/criar) com `paymentMethod.threeDSMode` `managed` e o objeto `browser`, e estar com status `authentication_required`. * Os dados do cartão da cobrança ficam guardados por 15 minutos. Depois disso, a retomada falha com `422`. * O resultado da autenticação 3DS vem de [`POST /v1/three-ds/challenge-result`](/referencia/3d-secure/resultado-desafio). * Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) como usuário do Basic, com senha vazia. ## Parâmetros de caminho **id** `string` *required* ID da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. ## Corpo da requisição **threeDS** `object` *required* Dados da autenticação 3D Secure (schema `CreditCardThreeDS`). O objeto é obrigatório: `threeDS: null` responde `400`. Nos campos opcionais, omita o campo quando não tiver valor. Não envie `null`: um `null` sobrescreve o valor que já estava guardado na cobrança. **propriedades** **type** `string` *required* Tipo de autenticação 3DS. Ex.: `full`. **state** `string` *required* Estado da autenticação: `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled`. Ex.: `success`. **cryptogram** `string` CAVV (valor de autenticação), criptograma em Base64 gerado na autenticação. Com `state` `success`, envie sempre. Ex.: `Vt5xwasruB0Q6qRoG9mpzdRPqQs=`. **eci** `string` Electronic Commerce Indicator. Valores comuns: `05` (autenticado), `06` (tentativa), `07` (não autenticado). Com `state` `success`, envie sempre. Ex.: `05`. **version** `string` Versão do protocolo 3DS (ex.: `2.1.0`, `2.2.0`). Ex.: `2.2.0`. **directoryServerTransactionId** `string` ID da transação no Directory Server (bandeira). Ex.: `607bb317-8d24-45a7-a3c0-7ae1fdca56d0`. **threeDsServerTransactionId** `string` ID da transação no 3DS Server. Ex.: `59588a8b-955e-4aa8-bae1-338bbfdba8fa`. **acsTransactionId** `string` ID da transação no ACS (banco emissor). Ex.: `6bf18a7a-3a7b-488f-bce1-3da96c73e746`. > [!NOTE] > > O schema `CreditCardThreeDS` também lista `mode`, `deviceData` e `challenge`. Não envie esses campos: `mode` é de uso interno e `deviceData` e `challenge` não são lidos no 3DS da Finvia. ## Respostas A resposta `200` tem o formato da cobrança criada (schema `CreatedCharge`). **id** `string` *required* Identificador único da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **status** `string` *required* Status da cobrança depois do processamento: `paid`, `pending`, `refused` ou `failed`. Ex.: `paid`. **paymentDetails** `object | null` *required* Detalhes do cartão usado. **propriedades** **firstSix** `string` *required* Seis primeiros dígitos do cartão. Ex.: `411111`. **lastFour** `string` *required* Quatro últimos dígitos do cartão. Ex.: `1111`. **expirationMonth** `string` *required* Mês de validade. Ex.: `10`. **expirationYear** `string` *required* Ano de validade. Ex.: `2028`. **holderName** `string` *required* Nome do titular. Ex.: `ANA LIMA`. **installments** `number` *required* Número de parcelas usado. Ex.: `2`. **reason** `string | null` *required* Motivo do status, principalmente em cobranças recusadas. Quando a autenticação não passou, vem no formato `3ds_: Authentication did not succeed`. | HTTP | Significado | Mensagem (`message`) | | - | - | - | | `200` | Cobrança retomada e processada | | | `400` | A cobrança não usa o 3DS gerenciado | `Cobrança não está utilizando 3DS gerenciado` | | `400` | Corpo inválido (por exemplo, sem `threeDS`, ou `type` ou `state` nulos) | Lista de mensagens de validação | | `401` | Chave pública inválida | `Unauthorized` | | `404` | Cobrança inexistente, de outra conta ou fora de `authentication_required` | `Cobrança não encontrada ou não está aguardando autenticação` | | `422` | Dados do cartão ausentes | `Dados do cartão não encontrados. Crie uma nova cobrança.` | | `422` | Dados do cartão expirados (mais de 15 minutos) | `Dados do cartão expiraram. Crie uma nova cobrança.` | | `422` | Dados da autenticação expirados | `Dados de autenticação expiraram. Crie uma nova cobrança.` | Os erros vêm no formato `{ statusCode, message, error }`. Trate o erro pelo código HTTP, não pelo texto: as mensagens misturam português e inglês e são exibidas aqui exatamente como a API devolve. > [!WARNING] > > Depois de um `422`, a cobrança não é processada e não pode mais ser retomada. Crie uma nova cobrança. Não trate a cobrança antiga como paga. > [!WARNING] > > O código `200` confirma que a cobrança foi processada. Para saber se ela foi paga, leia o `status`: `paid` libera o pedido; `refused` e `failed` encerram a tentativa, com o motivo em `reason`. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` | A cobrança já saiu de `authentication_required` (foi retomada antes), não existe ou é de outra conta | Consulte `GET /v1/charges/{id}` e use o status atual. Não chame esta rota duas vezes para a mesma cobrança | | `400` `Cobrança não está utilizando 3DS gerenciado` | A cobrança foi criada sem `threeDSMode` `managed` | Para 3DS feito por você, envie `paymentMethod.threeDS` na criação | | `422` com "expiraram" | A autenticação terminou depois do prazo de 15 minutos | Crie uma nova cobrança | | `401` | Chave pública inválida ou de outro ambiente | Use a `pk_` (ou `pk_test_`) da conta que criou a cobrança | | `200` com `status` `refused` | Autenticação sem sucesso ou recusa do emissor | Leia `reason` e ofereça nova tentativa ou outro meio | ```http REST (JSON) theme={null} POST /v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resume-3ds HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746" } } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resume-3ds" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "threeDS": { "type": "full", "state": "success", "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=", "eci": "05", "version": "2.2.0", "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0", "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa", "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746" } }' ``` ```javascript Navegador theme={null} const response = await fetch( `https://api-global.fastpaybrasil.com/v1/charges/${chargeId}/resume-3ds`, { method: 'POST', headers: { Authorization: 'Basic ' + btoa(`${FINVIA_PUBLIC_KEY}:`), 'Content-Type': 'application/json', }, body: JSON.stringify({ threeDS: resultadoDaAutenticacao }), }, ); const charge = await response.json(); ``` ```json 200 theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "paid", "paymentDetails": { "firstSix": "411111", "lastFour": "1111", "expirationMonth": "10", "expirationYear": "2028", "holderName": "ANA LIMA", "installments": 2 }, "reason": null } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Cobrança não encontrada ou não está aguardando autenticação", "error": "Not Found" } ``` ```json 422 theme={null} { "statusCode": 422, "message": "Dados de autenticação expiraram. Crie uma nova cobrança.", "error": "Unprocessable Entity" } ``` ## Veja também > [card] [3DS gerenciado](/guias/3d-secure/gerenciado) > > Guia do fluxo gerenciado pela Finvia. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Campos `threeDSMode`, `browser` e `authenticationUrl`. > [card] [Obter resultado do 3DS](/referencia/3d-secure/resultado-desafio) > > Origem do objeto `threeDS`. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos disparados após a retomada. # Consultar domínio Apple Pay Source: https://docs.fastpaybrasil.com/referencia/apple-pay/consultar-dominio GET /v1/apple-pay/domains/{id} Devolve um domínio Apple Pay da sua conta pelo id, com o status e o arquivo de verificação. Esta rota devolve um domínio Apple Pay pelo `id` do registro. Use para ler de novo o arquivo de verificação (`verificationFile`) ou para acompanhar o `status` depois de uma validação. ## Quando usar | Situação | O que fazer | | - | - | | Precisa do conteúdo do arquivo de verificação de novo | Leia `verificationFile.content` | | A validação falhou | Leia `lastVerificationError` para saber o motivo | | Conferir se o domínio continua `verified` | Leia `status` e `verifiedAt` | ## Antes de chamar * Use a **chave secreta** (`sk_`) no seu backend. * O usuário dono da chave precisa da permissão de domínios Apple Pay (perfis **Owner**, **Manager** e **Desenvolvedor**). * Tenha o `id` devolvido por [`POST /v1/apple-pay/domains`](/referencia/apple-pay/registrar-dominio) ou pela [listagem](/referencia/apple-pay/listar-dominios). ## Parâmetros de caminho **id** `string` *required* Identificador do registro de domínio. Ex.: `2xYq8Lm3NcR7tVb1KdZ4wP6sQhE`. ## Respostas A resposta `200` é o objeto Domínio, com o arquivo de verificação. **id** `string` Identificador do registro. **domain** `string` Hostname registrado, em minúsculas. **status** `string` `pending` (aguardando verificação), `verified` (pronto para uso) ou `failed` (a última verificação falhou). **verifiedAt** `string | null` Data e hora da verificação, em ISO 8601. `null` enquanto o domínio não estiver `verified`. **lastVerificationError** `string | null` Motivo da última falha de verificação. **verificationFile** `object` Arquivo de verificação. **propriedades** **path** `string | null` Localização do arquivo informada pelo processador, quando disponível. **content** `string | null` Conteúdo a servir em `/.well-known/apple-developer-merchantid-domain-association`, sem alterações. **createdAt** `string` Data e hora do registro, em ISO 8601. **updatedAt** `string` Data e hora da última atualização, em ISO 8601. | HTTP | Significado | Corpo | | - | - | - | | `200` | Domínio encontrado | Objeto Domínio | | `401` | Credencial inválida | `{ "statusCode": 401, "message": "Unauthorized" }` | | `403` | Usuário dono da chave sem permissão de domínios Apple Pay | `{ "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" }` | | `404` | Domínio inexistente ou de outra conta | `{ "code": "APPLE_PAY_DOMAIN_NOT_FOUND", "message": "..." }` | ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `APPLE_PAY_DOMAIN_NOT_FOUND` | `id` errado ou de outra conta | Localize o `id` pela [listagem](/referencia/apple-pay/listar-dominios) | | `status` `failed` | O arquivo não estava acessível na última validação | Leia `lastVerificationError`, corrija a hospedagem e [valide de novo](/referencia/apple-pay/validar-dominio) | ```http REST (JSON) theme={null} GET /v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE', { headers: { Authorization: `Basic ${credentials}` } }, ); const dominio = await response.json(); console.log(dominio.status, dominio.lastVerificationError); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "id": "2xYq8Lm3NcR7tVb1KdZ4wP6sQhE", "domain": "checkout.minhaloja.com.br", "status": "failed", "verifiedAt": null, "lastVerificationError": "...", "verificationFile": { "path": "https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association", "content": "7B227073706964223A22..." }, "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:03:00.000Z" } ``` ```json 404 theme={null} { "code": "APPLE_PAY_DOMAIN_NOT_FOUND", "message": "..." } ``` ## Veja também > [card] [Validar domínio](/referencia/apple-pay/validar-dominio) > > Confirme o arquivo hospedado. > [card] [Guia de Apple Pay](/guias/cobrancas/apple-pay) > > Como hospedar o arquivo de verificação. # Listar domínios Apple Pay Source: https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios GET /v1/apple-pay/domains Lista todos os domínios Apple Pay registrados na sua conta, com o status de verificação de cada um. Esta rota mostra os domínios Apple Pay da sua conta e em que situação cada um está. Use para conferir se o hostname do checkout está `verified` antes de publicar o botão e para montar uma tela de configuração no seu sistema. ## Quando usar | Situação | O que fazer | | - | - | | Conferir se o checkout está pronto | Procure o hostname exato da página e confira `status: "verified"` | | Investigar `APPLE_PAY_DOMAIN_NOT_VERIFIED` na validação de sessão | Veja se o hostname enviado pelo navegador está na lista e verificado | | Recuperar o `id` de um domínio | Localize pelo campo `domain` | ## Antes de chamar * Use a **chave secreta** (`sk_`) no seu backend. * O usuário dono da chave precisa da permissão de domínios Apple Pay (perfis **Owner**, **Manager** e **Desenvolvedor**). Esta rota não tem parâmetros. A lista não é paginada, vem do registro mais recente para o mais antigo e traz só os domínios da própria conta. ## Respostas **data** `object[]` Domínios registrados na conta. **propriedades do domínio** **id** `string` Identificador do registro. **domain** `string` Hostname registrado, em minúsculas. **status** `string` `pending`, `verified` ou `failed`. **verifiedAt** `string | null` Data e hora da verificação, em ISO 8601. **lastVerificationError** `string | null` Motivo da última falha de verificação. **verificationFile** `object` Arquivo de verificação: `path` e `content` (ambos podem vir `null`). **createdAt** `string` Data e hora do registro, em ISO 8601. **updatedAt** `string` Data e hora da última atualização, em ISO 8601. O significado de cada campo está em [Registrar domínio](/referencia/apple-pay/registrar-dominio#respostas). | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista obtida | `{ "data": [...] }` | | `401` | Credencial inválida | `{ "statusCode": 401, "message": "Unauthorized" }` | | `403` | Usuário dono da chave sem permissão de domínios Apple Pay | `{ "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" }` | ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Lista vazia | Nenhum domínio registrado nesta conta | Registre com [`POST /v1/apple-pay/domains`](/referencia/apple-pay/registrar-dominio) | | O hostname aparece, mas `pending` | O domínio ainda não foi validado | Hospede o arquivo e chame a [validação](/referencia/apple-pay/validar-dominio) | | `www.minhaloja.com.br` não aparece, mas `minhaloja.com.br` sim | Cada hostname é um registro separado | Registre também o hostname com `www` | ```http REST (JSON) theme={null} GET /v1/apple-pay/domains HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl "https://api-global.fastpaybrasil.com/v1/apple-pay/domains" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/apple-pay/domains', { headers: { Authorization: `Basic ${credentials}` }, }); const { data } = await response.json(); const checkout = data.find((d) => d.domain === 'checkout.minhaloja.com.br'); console.log(checkout?.status ?? 'não registrado'); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/apple-pay/domains")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/apple-pay/domains"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/apple-pay/domains") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "data": [ { "id": "2xYq8Lm3NcR7tVb1KdZ4wP6sQhE", "domain": "checkout.minhaloja.com.br", "status": "verified", "verifiedAt": "2026-10-27T18:05:00.000Z", "lastVerificationError": null, "verificationFile": { "path": "https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association", "content": "7B227073706964223A22..." }, "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:05:00.000Z" } ] } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" } ``` ## Veja também > [card] [Consultar domínio](/referencia/apple-pay/consultar-dominio) > > Um domínio pelo `id`. > [card] [Guia de Apple Pay](/guias/cobrancas/apple-pay) > > Fluxo completo, do domínio à cobrança. # Registrar domínio Apple Pay Source: https://docs.fastpaybrasil.com/referencia/apple-pay/registrar-dominio POST /v1/apple-pay/domains Registra o hostname onde o botão Apple Pay aparece e devolve o arquivo de verificação que você precisa hospedar. Esta rota é o primeiro passo para aceitar Apple Pay no seu site. Você informa o hostname da página de checkout, a Finvia registra o domínio no processador e devolve o arquivo de verificação. Depois de hospedar o arquivo, você confirma o domínio em [`POST /v1/apple-pay/domains/{id}/validate`](/referencia/apple-pay/validar-dominio). > [!WARNING] > > Registrar o **primeiro domínio** ativa na sua conta o modelo de Apple Pay em que a sessão é validada por [`POST /v1/apple-pay/validate-merchant`](/referencia/apple-pay/validar-sessao). É este passo que liga o Apple Pay na sua integração. Se a sua conta já operava Apple Pay com certificado próprio, leia a seção de migração do [guia de Apple Pay](/guias/cobrancas/apple-pay) antes de registrar. ## Quando usar | Situação | O que fazer | | - | - | | Primeira integração com Apple Pay | Registre cada hostname onde o botão aparece | | Novo subdomínio de checkout | Registre o novo hostname. `www` e o domínio raiz são registros diferentes | | Perdeu o `id` ou o arquivo de verificação | Registre de novo o mesmo hostname: a rota devolve o registro que já existe | ## Antes de chamar * Use a **chave secreta** (`sk_`) no seu backend, no formato Basic (a chave como usuário, senha vazia). * O usuário dono da chave precisa da permissão de domínios Apple Pay (perfis **Owner**, **Manager** e **Desenvolvedor**). Sem ela, a API responde `403`. * O registro não separa produção de teste: um domínio registrado vale para os dois modos. ## Corpo da requisição **domain** `string` *required* Hostname onde o botão Apple Pay aparece, com até 255 caracteres. Só o hostname: sem `https://`, sem porta e sem caminho. Endereço IP não é aceito. O valor é gravado em minúsculas. Ex.: `checkout.minhaloja.com.br`. > [!NOTE] > > Não envie outros campos no corpo. Registre exatamente o hostname que o navegador mostra em `window.location.hostname`: cada subdomínio é um registro separado. ## Respostas A resposta `201` é o objeto Domínio. A rota é idempotente: se a mesma conta registrar de novo o mesmo hostname, recebe o mesmo objeto, também com `201`. **id** `string` Identificador do registro. Use na validação e na consulta. Ex.: `2xYq8Lm3NcR7tVb1KdZ4wP6sQhE`. **domain** `string` Hostname registrado, em minúsculas. Ex.: `checkout.minhaloja.com.br`. **status** `string` Situação do domínio: `pending` (aguardando verificação), `verified` (pronto para uso) ou `failed` (a última verificação falhou; veja `lastVerificationError`). **verifiedAt** `string | null` Data e hora da verificação, em ISO 8601. `null` enquanto o domínio não estiver `verified`. **lastVerificationError** `string | null` Motivo da última falha de verificação. `null` quando não houve falha. **verificationFile** `object` Arquivo que você precisa hospedar no domínio. **propriedades** **path** `string | null` Localização do arquivo informada pelo processador, quando disponível. O caminho que precisa responder é sempre `/.well-known/apple-developer-merchantid-domain-association`. **content** `string | null` Conteúdo do arquivo, a ser servido como está, sem decodificar. Se vier `null`, não repita a chamada: fale com o suporte. **createdAt** `string` Data e hora do registro, em ISO 8601. **updatedAt** `string` Data e hora da última atualização, em ISO 8601. | HTTP | Significado | Código ou mensagem | | - | - | - | | `201` | Domínio registrado (ou registro já existente devolvido) | Objeto Domínio | | `400` | `domain` não é um hostname válido | `APPLE_PAY_INVALID_DOMAIN` | | `400` | O processador recusou o registro | `APPLE_PAY_PROVIDER_REJECTED` | | `400` | Corpo inválido (campo ausente ou acima de 255 caracteres) | Lista de mensagens de validação | | `401` | Credencial inválida | `Unauthorized` | | `403` | Usuário dono da chave sem permissão de domínios Apple Pay | `Acesso negado` | | `409` | Dois registros simultâneos do mesmo hostname (raro) | `APPLE_PAY_DOMAIN_ALREADY_REGISTERED` | | `422` | Processador de Apple Pay não configurado para a sua conta | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | | `500` | Falha de autenticação entre a Finvia e o processador | `APPLE_PAY_PROVIDER_AUTH_FAILED` | | `503` | Processador indisponível | `APPLE_PAY_PROVIDER_UNAVAILABLE` | ### Formato dos erros | Tipo de erro | Corpo | | - | - | | Erro de negócio (códigos `APPLE_PAY_*`) | `{ "code": "...", "message": "..." }`, sem `statusCode` | | Validação de campo | `{ "statusCode": 400, "message": [...], "error": "Bad Request" }` | | Credencial inválida | `{ "statusCode": 401, "message": "Unauthorized" }` | | Sem permissão | `{ "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" }` | Trate o erro pelo código HTTP e pelo campo `code`, não pelo texto de `message`. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` `APPLE_PAY_INVALID_DOMAIN` | `domain` com `https://`, porta, caminho ou IP | Envie só o hostname, ex.: `checkout.minhaloja.com.br` | | `409` `APPLE_PAY_DOMAIN_ALREADY_REGISTERED` | Duas chamadas simultâneas para o mesmo hostname | Repita a chamada: o registro existente é devolvido | | `403` `Acesso negado` | Chave de usuário sem permissão de domínios Apple Pay | Gere a chave com um usuário Owner, Manager ou Desenvolvedor | | `422` `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | Conta sem processador de Apple Pay | Fale com o suporte | | `503` `APPLE_PAY_PROVIDER_UNAVAILABLE` | Processador indisponível no momento | Tente de novo em alguns minutos | ```http REST (JSON) theme={null} POST /v1/apple-pay/domains HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "domain": "checkout.minhaloja.com.br" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/apple-pay/domains" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "domain": "checkout.minhaloja.com.br" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/apple-pay/domains', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ domain: 'checkout.minhaloja.com.br' }), }); const dominio = await response.json(); // Guarde dominio.id e publique dominio.verificationFile.content no seu site console.log(dominio.id, dominio.status); ``` ```python Python theme={null} import os import requests payload = { "domain": "checkout.minhaloja.com.br", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'checkout.minhaloja.com.br', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/apple-pay/domains'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "domain": "checkout.minhaloja.com.br" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/apple-pay/domains")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "domain": "checkout.minhaloja.com.br" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/apple-pay/domains"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "domain": "checkout.minhaloja.com.br" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/apple-pay/domains") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "domain" => "checkout.minhaloja.com.br", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "id": "2xYq8Lm3NcR7tVb1KdZ4wP6sQhE", "domain": "checkout.minhaloja.com.br", "status": "pending", "verifiedAt": null, "lastVerificationError": null, "verificationFile": { "path": "https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association", "content": "7B227073706964223A22..." }, "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:00:00.000Z" } ``` ```json 400 theme={null} { "code": "APPLE_PAY_INVALID_DOMAIN", "message": "..." } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" } ``` ## Veja também > [card] [Validar domínio](/referencia/apple-pay/validar-dominio) > > Confirme o arquivo hospedado. > [card] [Guia de Apple Pay](/guias/cobrancas/apple-pay) > > Fluxo completo, do domínio à cobrança. > [card] [Listar domínios](/referencia/apple-pay/listar-dominios) > > Todos os domínios da conta. > [card] [Validar sessão](/referencia/apple-pay/validar-sessao) > > Chamada feita pelo navegador a cada compra. # Validar domínio Apple Pay Source: https://docs.fastpaybrasil.com/referencia/apple-pay/validar-dominio POST /v1/apple-pay/domains/{id}/validate Confere o arquivo de verificação hospedado no seu domínio e, se estiver correto, deixa o domínio pronto para o Apple Pay. Depois de registrar o domínio e hospedar o arquivo de verificação, chame esta rota para que o processador confira o arquivo. Quando a conferência passa, o domínio fica `verified` e o botão Apple Pay pode ser usado nas páginas desse hostname. ## Quando usar | Situação | O que fazer | | - | - | | Acabou de hospedar o arquivo | Chame a validação | | A validação anterior falhou | Corrija a hospedagem e chame de novo | | Mudou a infraestrutura do site (CDN, servidor, redirecionamentos) | Valide de novo para confirmar que o arquivo continua acessível | ## Antes de chamar * Use a **chave secreta** (`sk_`) no seu backend. * O usuário dono da chave precisa da permissão de domínios Apple Pay (perfis **Owner**, **Manager** e **Desenvolvedor**). * Publique o conteúdo de `verificationFile.content` em `https:///.well-known/apple-developer-merchantid-domain-association`: caminho sem extensão, `Content-Type: text/plain`, HTTPS válido, resposta `200`, sem redirecionamento e sem autenticação. Confira antes de validar: ```bash theme={null} curl -sI "https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association" # HTTP/2 200 # content-type: text/plain ``` ## Parâmetros de caminho **id** `string` *required* Identificador do registro de domínio, devolvido por [`POST /v1/apple-pay/domains`](/referencia/apple-pay/registrar-dominio). Ex.: `2xYq8Lm3NcR7tVb1KdZ4wP6sQhE`. Esta rota não tem corpo. ## Respostas A resposta `200` é o objeto Domínio atualizado (os campos estão em [Registrar domínio](/referencia/apple-pay/registrar-dominio#respostas)). Quando a conferência passa, vem `status: "verified"` e `verifiedAt` preenchido. Quando a conferência falha, a API responde `422` `APPLE_PAY_DOMAIN_VERIFICATION_FAILED`, o domínio passa a `failed`, `verifiedAt` volta a `null` e o motivo fica em `lastVerificationError`. Consulte com [`GET /v1/apple-pay/domains/{id}`](/referencia/apple-pay/consultar-dominio) para ler o motivo. | HTTP | Significado | Código ou mensagem | | - | - | - | | `200` | Domínio verificado | Objeto Domínio | | `401` | Credencial inválida | `Unauthorized` | | `403` | Usuário dono da chave sem permissão de domínios Apple Pay | `Acesso negado` | | `404` | Domínio inexistente ou de outra conta | `APPLE_PAY_DOMAIN_NOT_FOUND` | | `422` | Arquivo ausente, inacessível ou diferente do esperado | `APPLE_PAY_DOMAIN_VERIFICATION_FAILED` | | `422` | Processador de Apple Pay não configurado para a sua conta | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | | `500` | Falha de autenticação entre a Finvia e o processador | `APPLE_PAY_PROVIDER_AUTH_FAILED` | | `503` | Processador indisponível | `APPLE_PAY_PROVIDER_UNAVAILABLE` | Os erros `APPLE_PAY_*` vêm no formato `{ "code": "...", "message": "..." }`, sem `statusCode`. Os erros `401` e `403` seguem o formato padrão, com `statusCode`. > [!TIP] > > O domínio está pronto quando esta rota responde `200` com `status: "verified"` para o hostname exato da página do checkout. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `422` `APPLE_PAY_DOMAIN_VERIFICATION_FAILED` | Caminho com extensão (`.txt`), redirecionamento HTTP para HTTPS ou para `www`, `Content-Type` diferente de `text/plain` ou conteúdo alterado | Rode o `curl -sI` acima, corrija e valide de novo | | `404` `APPLE_PAY_DOMAIN_NOT_FOUND` | `id` errado ou de outra conta | Localize o `id` pela [listagem](/referencia/apple-pay/listar-dominios) | | `503` `APPLE_PAY_PROVIDER_UNAVAILABLE` | Processador indisponível no momento | Tente de novo em alguns minutos | ```http REST (JSON) theme={null} POST /v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate', { method: 'POST', headers: { Authorization: `Basic ${credentials}` } }, ); const body = await response.json(); if (response.status === 200 && body.status === 'verified') { console.log('Domínio pronto para o Apple Pay'); } else { console.warn('Falha na verificação:', body.code); } ``` ```python Python theme={null} import os import requests response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate")) .header("Authorization", "Basic " + credentials) .method("POST", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "id": "2xYq8Lm3NcR7tVb1KdZ4wP6sQhE", "domain": "checkout.minhaloja.com.br", "status": "verified", "verifiedAt": "2026-10-27T18:05:00.000Z", "lastVerificationError": null, "verificationFile": { "path": "https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association", "content": "7B227073706964223A22..." }, "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:05:00.000Z" } ``` ```json 422 theme={null} { "code": "APPLE_PAY_DOMAIN_VERIFICATION_FAILED", "message": "..." } ``` ## Veja também > [card] [Validar sessão](/referencia/apple-pay/validar-sessao) > > Próximo passo: a chamada feita pelo navegador. > [card] [Guia de Apple Pay](/guias/cobrancas/apple-pay) > > Exemplos de hospedagem em Node.js e Nginx. # Validar sessão Apple Pay Source: https://docs.fastpaybrasil.com/referencia/apple-pay/validar-sessao POST /v1/apple-pay/validate-merchant Chamada feita pelo navegador no evento onvalidatemerchant: devolve a sessão de merchant da Apple que abre a folha de pagamento. A cada compra, quando o cliente toca no botão Apple Pay, o Apple Pay JS dispara o evento `onvalidatemerchant` e pede uma sessão de merchant. O seu front-end chama esta rota com a `validationURL` recebida da Apple e o hostname da página, e repassa a resposta para `session.completeMerchantValidation()`. Sem esse passo, a folha de pagamento não abre. > [!NOTE] > > **Para o negócio:** esta é a única chamada do fluxo feita pelo navegador do cliente. Ela usa a chave pública, que pode ficar no código do site. A cobrança continua sendo criada pelo seu backend, com a chave secreta. ## Autenticação com a chave pública Esta rota usa **Basic com a chave pública** (`pk_` em produção ou `pk_test_` no Modo Teste) como usuário e senha vazia: `Authorization: Basic base64("pk_...:")`. A chave secreta (`sk_`) não deve ir para o navegador. * A conta dona da chave pública precisa estar ativa. * A sessão é sempre validada no provedor real, mesmo com `pk_test_`, porque a folha do Safari só abre com uma sessão real. A cobrança feita depois com a chave de teste cai no ambiente de teste. ## Quando usar | Situação | O que fazer | | - | - | | Evento `onvalidatemerchant` disparado | Chame esta rota uma vez e repasse a resposta à Apple | | Cliente fechou e abriu a folha de novo | Uma nova sessão gera um novo `onvalidatemerchant`: chame de novo | | Teste em laço ou várias chamadas por clique | Evite: há limite de tentativas por IP | ## Antes de chamar * O hostname da página está registrado e `verified` na conta da chave pública ([Registrar domínio](/referencia/apple-pay/registrar-dominio) e [Validar domínio](/referencia/apple-pay/validar-dominio)). * A conta já registrou pelo menos um domínio. Sem nenhum, a API responde `422` `APPLE_PAY_PROVIDER_NOT_ENABLED`. ## Corpo da requisição **validationUrl** `string` *required* O valor de `event.validationURL` recebido no `onvalidatemerchant`. Precisa ser `https`, com host `apple.com` ou um subdomínio dele, sem porta e com até 2048 caracteres. Repasse sem alterar. **domain** `string` *required* O hostname da página, `window.location.hostname`, com até 255 caracteres. Precisa ser um domínio registrado e verificado na conta da chave pública. Ex.: `checkout.minhaloja.com.br`. ## Respostas A resposta `200` é o objeto de sessão de merchant da Apple. Ele é **opaco**: não leia nem altere os campos. Repasse o objeto inteiro, como veio, para `session.completeMerchantValidation()`. | HTTP | Significado | Código ou mensagem | | - | - | - | | `200` | Sessão criada | Objeto de sessão da Apple | | `400` | `validationUrl` fora das regras (não `https`, host fora de `apple.com`, com porta ou longa demais) | `APPLE_PAY_INVALID_VALIDATION_URL` | | `400` | `domain` inválido | `APPLE_PAY_INVALID_DOMAIN` | | `400` | Domínio de outra conta, não registrado ou ainda não verificado | `APPLE_PAY_DOMAIN_NOT_VERIFIED` | | `401` | Chave pública inválida | `Unauthorized` | | `422` | A conta ainda não registrou nenhum domínio | `APPLE_PAY_PROVIDER_NOT_ENABLED` | | `422` | Processador de Apple Pay não configurado para a sua conta | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | | `429` | Limite de tentativas atingido: 20 por IP a cada 5 minutos, além de um teto global da plataforma | `APPLE_PAY_RATE_LIMITED` | | `500` | Falha de autenticação entre a Finvia e o processador | `APPLE_PAY_PROVIDER_AUTH_FAILED` | | `503` | Processador indisponível | `APPLE_PAY_PROVIDER_UNAVAILABLE` | Os erros `APPLE_PAY_*` vêm no formato `{ "code": "...", "message": "..." }`, sem `statusCode`. Erros de validação de campo vêm como `{ "statusCode": 400, "message": [...], "error": "Bad Request" }`. Em qualquer erro, chame `session.abort()` e ofereça outra forma de pagamento. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` `APPLE_PAY_DOMAIN_NOT_VERIFIED` | O `domain` enviado é diferente do registrado (ex.: `www`), é de outra conta ou ainda não está `verified` | Confira com [`GET /v1/apple-pay/domains`](/referencia/apple-pay/listar-dominios) e valide o domínio | | `422` `APPLE_PAY_PROVIDER_NOT_ENABLED` | Nenhum domínio registrado na conta | Registre o primeiro domínio: é o registro que habilita o fluxo | | `429` `APPLE_PAY_RATE_LIMITED` | Mais de 20 tentativas do mesmo IP em 5 minutos | Chame uma vez por `onvalidatemerchant`, sem repetir em laço | | `401` | Chave pública errada ou com a chave secreta no lugar | Use a `pk_` (ou `pk_test_`) da mesma conta que registrou o domínio | | A folha abre e fecha em seguida | A resposta foi alterada antes de chegar à Apple | Passe o JSON recebido direto para `completeMerchantValidation()` | ```javascript Navegador theme={null} session.onvalidatemerchant = async (event) => { try { const response = await fetch('https://api-global.fastpaybrasil.com/v1/apple-pay/validate-merchant', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Basic ' + btoa('pk_SUA_CHAVE_PUBLICA:'), }, body: JSON.stringify({ validationUrl: event.validationURL, domain: window.location.hostname, }), }); if (!response.ok) throw new Error('validate-merchant falhou'); session.completeMerchantValidation(await response.json()); } catch (error) { session.abort(); } }; ``` ```http REST (JSON) theme={null} POST /v1/apple-pay/validate-merchant HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession", "domain": "checkout.minhaloja.com.br" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/apple-pay/validate-merchant" \ -u "$FINVIA_PUBLIC_KEY:" \ -H "Content-Type: application/json" \ -d '{ "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession", "domain": "checkout.minhaloja.com.br" }' ``` ```json 200 theme={null} { "epochTimestamp": 1761588000000, "expiresAt": 1761591600000, "merchantSessionIdentifier": "...", "nonce": "...", "merchantIdentifier": "...", "domainName": "checkout.minhaloja.com.br", "displayName": "...", "signature": "..." } ``` ```json 400 theme={null} { "code": "APPLE_PAY_DOMAIN_NOT_VERIFIED", "message": "..." } ``` > [!NOTE] > > O exemplo `200` mostra a forma usual da sessão da Apple, com valores omitidos. O conteúdo é definido pela Apple e pode mudar: trate o objeto como opaco. ## Veja também > [card] [Guia de Apple Pay](/guias/cobrancas/apple-pay) > > Fluxo completo no navegador e no backend. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Envio do token em `paymentMethod.wallet`. > [card] [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) > > Onde obter a chave pública. > [card] [Listar domínios](/referencia/apple-pay/listar-dominios) > > Confira os domínios verificados. # Atualizar uma assinatura Source: https://docs.fastpaybrasil.com/referencia/assinaturas/atualizar PATCH /v1/subscriptions/{id} Atualiza o metadata de uma assinatura ativa. É o único campo que pode ser alterado. Esta rota atualiza as informações livres (`metadata`) de uma assinatura ativa, como o ID do usuário no seu sistema, a campanha de origem ou uma observação do atendimento. Cartão, plano, valor e pausa **não** podem ser alterados aqui nem em nenhuma outra rota. ## Quando usar | Situação | Como usar esta rota | | - | - | | Vincular a assinatura ao ID do usuário no seu sistema | `metadata` com o seu identificador | | Marcar um cliente (VIP, parceria, campanha) | `metadata` com a marcação | | Trocar o cartão da assinatura | Não existe troca. Cancele e crie outra assinatura com o novo cartão | | Trocar de plano (upgrade ou downgrade) | Não existe troca. Cancele e crie outra assinatura no novo plano | | Pausar a cobrança | Não existe pausa | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **atualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * A assinatura precisa estar com status `active`. Nos demais status a resposta é `400`. Esta rota não serve para destravar uma assinatura `pending_activation`. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). > [!WARNING] > > Não existe troca de cartão, troca de plano, alteração de valor nem pausa. Para trocar o cartão ou o plano, **cancele a assinatura e crie outra**. A nova assinatura começa um ciclo novo, com cobrança imediata. Leve isso em conta: o cliente pode pagar o novo ciclo antes do fim do período já pago da assinatura anterior. ## Parâmetros de caminho **id** `string` *required* Identificador único da assinatura. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Corpo da requisição Apenas `metadata` pode ser atualizado. **metadata** `object` Informações suas, em formato livre, guardadas na assinatura. Ex.: `{"notes": "Cliente VIP"}`. ## Respostas **success** `boolean` Indica se a atualização foi feita. Ex.: `true`. **id** `string` ID da assinatura. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **metadata** `object` `metadata` atualizado. Ex.: `{"notes": "VIP customer"}`. | HTTP | Significado | Corpo | | - | - | - | | `200` | Assinatura atualizada | `success`, `id`, `metadata` | | `400` | Só assinaturas ativas podem ser atualizadas | `{"statusCode": 400, "message": "Only active subscriptions can be updated"}` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão atualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Assinatura não encontrada | `{"statusCode": 404, "message": "Subscription not found"}` | > [!NOTE] > > **Para o negócio:** o `metadata` da assinatura volta nos webhooks de assinatura (campo `data.metadata`) e na [consulta da assinatura](/referencia/assinaturas/consultar). Gravar ali o identificador do cliente no seu sistema facilita a conciliação de cada evento com a conta certa. > [!TIP] > > **Para o desenvolvedor:** a documentação não diz se o `metadata` enviado é mesclado ao existente ou se o substitui. Para não perder chaves, consulte a assinatura, monte o objeto completo e envie tudo de uma vez. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` "Only active subscriptions can be updated" | Assinatura `pending_activation`, `cancelled` ou `expired` | Só atualize assinaturas `active` | | Assinatura `pending_activation` não sai do lugar | Esta rota não reativa assinaturas, e a API não tenta de novo a primeira cobrança | Crie uma nova assinatura com outro cartão e cancele a pendente (veja [Criar assinatura](/referencia/assinaturas/criar)) | | `404` "Subscription not found" | `id` errado ou de outra conta | Confira o `id` em [Listar assinaturas](/referencia/assinaturas/listar) | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão atualizar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Cartão ou plano continuam os mesmos depois da chamada | Só `metadata` é atualizável | Cancele e crie outra assinatura | ```http REST (JSON) theme={null} PATCH /v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "metadata": { "notes": "Cliente VIP" } } ``` ```bash cURL theme={null} curl -X PATCH "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "metadata": { "notes": "Cliente VIP" } }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q', { method: 'PATCH', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ metadata: { notes: 'Cliente VIP', internalUserId: '12345' }, }), }, ); const result = await response.json(); ``` ```python Python theme={null} import os import requests payload = { "metadata": { "notes": "Cliente VIP", }, } response = requests.request( "PATCH", "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} [ 'notes' => 'Cliente VIP', ], ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'PATCH', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "metadata": { "notes": "Cliente VIP" } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "metadata": { "notes": "Cliente VIP" } } """; var request = new HttpRequestMessage(HttpMethod.Patch, "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "metadata": { "notes": "Cliente VIP" } }`) req, err := http.NewRequest("PATCH", "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Patch.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "metadata" => { "notes" => "Cliente VIP", }, }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "success": true, "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "metadata": { "notes": "VIP customer" } } ``` ```json 400 theme={null} { "statusCode": 400, "message": "Only active subscriptions can be updated" } ``` ## Veja também > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Registre o novo cartão antes de recriar a assinatura. > [card] [Cancelar assinatura](/referencia/assinaturas/cancelar) > > Primeiro passo para trocar cartão ou plano. # Cancelar uma assinatura Source: https://docs.fastpaybrasil.com/referencia/assinaturas/cancelar POST /v1/subscriptions/{id}/cancel Cancela uma assinatura. Até 7 dias da criação, estorna as cobranças pagas; depois disso, interrompe as cobranças sem estorno. Esta rota encerra a cobrança recorrente de uma assinatura. O efeito depende de **quando** o cancelamento acontece: em até 7 dias da criação, o cancelamento é do tipo arrependimento (`regret`) e estorna automaticamente todas as cobranças pagas; depois disso, as próximas cobranças não acontecem e não há estorno. A mesma rota é o primeiro passo para trocar o cartão ou o plano, já que a assinatura não aceita essas mudanças. > [!WARNING] > > A janela de 7 dias é uma **regra da plataforma** e vale para todo cancelamento feito nela, venha do lojista ou da Finvia, por qualquer motivo, também em venda entre empresas. Ela conta a partir da **criação da assinatura** (não da primeira cobrança nem da entrega), em dias completos: um cancelamento feito até 7 dias e 23 horas depois da criação ainda é `regret`. Não existe opção para cancelar dentro da janela sem estornar. ## Quando usar | Situação | Como usar esta rota | | - | - | | Cliente desistiu logo após assinar | Cancele em até 7 dias: as cobranças pagas são estornadas (`regret`) | | Cliente pediu para sair depois de meses | Cancele: as cobranças param e o acesso vale até o fim do período pago (`regular`) | | Trocar o cartão ou o plano | Cancele e crie outra assinatura em [Criar assinatura](/referencia/assinaturas/criar) | | Limpar uma assinatura `pending_activation` depois de criar outra com novo cartão | Cancele a pendente. Ela não cobra nada enquanto está pendente | | Homologação | Cancele no mesmo dia da criação para estornar a cobrança real do teste | | Estornar uma única cobrança avulsa | Use [Estornar cobrança](/referencia/cobrancas/estornar) | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **cancelar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * A assinatura não pode estar `cancelled` nem `expired`. Nesses casos a resposta é `400`. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). ## Tipos de cancelamento | | Arrependimento (`regret`) | Regular (`regular`) | | - | - | - | | Quando | Até 7 dias após a criação da assinatura (contados em dias completos) | Depois de 7 dias | | Estorno | Todas as cobranças pagas da assinatura: trial pago, primeira cobrança e renovações dentro do período | Não há estorno | | `refunded` | `true` se havia cobrança paga e todas foram estornadas; `false` se não havia cobrança paga (ex.: trial grátis) ou se um estorno não foi concluído | `false` | | Status | `cancelled` | `cancelled`, e as cobranças param imediatamente | | Acesso | Encerrado na hora (`accessRevokedAt`) | Continua até `accessRevokedAt`, o fim do período já pago (`current_period_end`). Quem controla esse acesso é a sua plataforma | | Webhook | `subscription.cancelled` com `cancellation_type: "regret"` | `subscription.cancelled` com `cancellation_type: "regular"` e `refunded: false` | > [!NOTE] > > **Para o negócio:** no cancelamento regular, a Finvia apenas para de cobrar: liberar ou bloquear o acesso ao serviço até `accessRevokedAt` é responsabilidade da sua plataforma. Defina essa regra com o time de produto antes de colocar o cancelamento no ar. ## Parâmetros de caminho **id** `string` *required* Identificador único da assinatura. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Corpo da requisição O corpo é opcional. **reason** `string` Motivo do cancelamento. Máximo de 500 caracteres (`maxLength` 500). Ex.: `Cliente solicitou cancelamento`. ## Respostas A resposta `200` tem um de dois formatos, conforme o tipo de cancelamento. ### Arrependimento (até 7 dias) **id** `string` ID da assinatura. **status** `string` Status da assinatura: `cancelled`. **cancellationType** `string` Tipo de cancelamento: `regret`. **refunded** `boolean` `true` quando havia cobranças pagas e todas foram estornadas. `false` quando não havia o que estornar (ex.: trial grátis) ou quando um estorno não foi concluído. **refundId** `string | null` ID do estorno. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **accessRevokedAt** `string` Momento em que o acesso foi revogado (formato `date-time`). ### Regular (depois de 7 dias) **id** `string` ID da assinatura. **status** `string` Status da assinatura: `cancelled`. **cancellationType** `string` Tipo de cancelamento: `regular`. **refunded** `boolean` `false` no cancelamento regular. (O contrato usa a mesma descrição do campo nas outras rotas: `true` só quando havia cobranças pagas e todas foram estornadas no arrependimento.) **accessRevokedAt** `string | null` Data até a qual o acesso do comprador continua valendo (fim do período pago), no formato `date-time`. O status já é `cancelled` e as cobranças já pararam: a sua plataforma mantém o acesso até essa data. | HTTP | Significado | Corpo | | - | - | - | | `200` | Assinatura cancelada | Formato de arrependimento ou regular | | `400` | Assinatura já cancelada ou expirada | `{"statusCode": 400, "message": "Subscription already cancelled or expired"}` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão cancelar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Assinatura não encontrada | `{"statusCode": 404, "message": "Subscription not found"}` | > [!NOTE] > > Depois do cancelamento, a Finvia envia o webhook `subscription.cancelled`, com `cancelled_at`, `cancellation_type` e `refunded`. Veja [Webhooks de assinatura](/guias/webhooks/assinatura). > [!TIP] > > **Para o desenvolvedor:** decida o acesso pelo `cancellationType`. Com `regret`, revogue imediatamente. Com `regular`, guarde o `accessRevokedAt` e mantenha o acesso até essa data. Não use `refunded` para decidir o acesso: ele pode vir `false` também no arrependimento (trial grátis ou estorno não concluído). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` "Subscription already cancelled or expired" | Assinatura já encerrada | Consulte o status em [Consultar assinatura](/referencia/assinaturas/consultar) antes de cancelar | | `404` "Subscription not found" | `id` errado ou de outra conta | Confira o `id` em [Listar assinaturas](/referencia/assinaturas/listar) | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão cancelar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | `refunded: false` em cancelamento dentro de 7 dias | Não havia cobrança paga (trial grátis) ou um estorno não foi concluído | Confira o histórico de `charges` na consulta da assinatura | | Cliente perdeu o acesso antes do fim do período pago | Acesso revogado pelo status `cancelled` no cancelamento regular | Mantenha o acesso até `accessRevokedAt` | | Cobrança de homologação não estornada | Cancelamento feito depois da janela de 7 dias | Cancele no mesmo dia da criação durante a homologação | ```http REST (JSON) theme={null} POST /v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "reason": "Cliente solicitou cancelamento" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "reason": "Cliente solicitou cancelamento" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ reason: 'Cliente solicitou cancelamento' }), }, ); const result = await response.json(); if (result.cancellationType === 'regret') { // revogue o acesso agora } else { // mantenha o acesso até result.accessRevokedAt } ``` ```python Python theme={null} import os import requests payload = { "reason": "Cliente solicitou cancelamento", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'Cliente solicitou cancelamento', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "reason": "Cliente solicitou cancelamento" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "reason": "Cliente solicitou cancelamento" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "reason": "Cliente solicitou cancelamento" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "reason" => "Cliente solicitou cancelamento", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 Arrependimento theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "cancelled", "cancellationType": "regret", "refunded": true, "refundId": "2RhQg9M7ZCg3X3nMb9W4kA1T", "accessRevokedAt": "2024-01-16T10:30:00.000Z" } ``` ```json 200 Regular theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "cancelled", "cancellationType": "regular", "refunded": false, "accessRevokedAt": "2024-02-15T10:30:00.000Z" } ``` ```json 400 theme={null} { "statusCode": 400, "message": "Subscription already cancelled or expired" } ``` ## Veja também > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Payload do `subscription.cancelled`. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Registre o novo cartão antes de recriar a assinatura. > [card] [Homologação](/homologacao/roteiro) > > Cenário SUB-06: cancelar dentro de 7 dias. # Consultar uma assinatura Source: https://docs.fastpaybrasil.com/referencia/assinaturas/consultar GET /v1/subscriptions/{id} Devolve todos os dados de uma assinatura, incluindo plano, cliente, merchant e o histórico de cobranças. Esta rota traz a ficha completa de uma assinatura: status atual, período vigente, dados do plano e do cliente, `metadata` e o **histórico de todas as tentativas de cobrança**, ciclo a ciclo. É a fonte para conferir o estado real depois de receber um webhook, montar a tela "Minha assinatura" e responder ao atendimento quando o cliente pergunta o que foi cobrado. ## Quando usar | Situação | Como usar esta rota | | - | - | | Ao receber um webhook `subscription.*` | Consulte pelo `data.id` para confirmar o status antes de liberar ou bloquear acesso | | Tela "Minha assinatura" | Exiba plano, período atual e histórico de `charges` | | Atendimento ao cliente | Veja quais ciclos foram pagos, recusados ou estornados, e o motivo da falha | | Abrir a cobrança de um ciclo em `GET /v1/charges/{id}` | Esta rota não traz o id da cobrança. Veja [Onde obter o id da cobrança](#onde-obter-o-id-da-cobrança) | | Controlar acesso depois de cancelamento regular | Use o `accessRevokedAt` devolvido por [Cancelar assinatura](/referencia/assinaturas/cancelar), a data até a qual o acesso vale (fim do período pago) | | Ver várias assinaturas de uma vez | Use [Listar assinaturas](/referencia/assinaturas/listar) | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **visualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager**, **Operador** e **Visualizador**. Os perfis Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Tenha o `id` da assinatura, devolvido na criação, na listagem ou no campo `data.id` dos webhooks de assinatura. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). ## Parâmetros de caminho **id** `string` *required* Identificador único da assinatura. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Respostas **id** `string` Identificador único da assinatura. **status** `string` Status da assinatura: | Valor | Significado | | - | - | | `pending_activation` | A primeira cobrança foi recusada ou está em análise. A assinatura não está ativa, não cobra, não renova e não tem retentativa automática. Se a análise aprovar o pagamento, passa a `active` automaticamente | | `active` | Ativa e em dia. Continua `active` durante as retentativas de cobrança | | `cancelled` | Cancelada | | `expired` | Encerrada: limite de retentativas esgotado ou o plano chegou ao `endDate` | **currentPeriodStart** `string | null` Início do período de cobrança atual (formato `date-time`). **currentPeriodEnd** `string | null` Fim do período de cobrança atual (formato `date-time`). **cancelledAt** `string | null` Data do cancelamento (formato `date-time`). `null` se não foi cancelada. **cancellationType** `string | null` Tipo de cancelamento: `regret` (até 7 dias da criação) ou `regular` (depois de 7 dias). `null` se não foi cancelada. **refunded** `boolean` `true` quando havia cobranças pagas e todas foram estornadas (cancelamento por arrependimento). `false` no cancelamento regular, no arrependimento sem cobrança paga (ex.: trial grátis) ou quando um estorno não foi concluído. **createdAt** `string` Data de criação (formato `date-time`). **updatedAt** `string` Data da última atualização (formato `date-time`). **plan** `object` Dados do plano assinado. **propriedades** **id** `string` ID do plano. **name** `string` Nome do plano. Ex.: `Plano Premium Mensal`. **price** `number` Preço do plano, em reais. Ex.: `99.9`. **currency** `string` Código da moeda. Ex.: `BRL`. **recurrenceType** `string` Periodicidade. Ex.: `monthly`. **customer** `object` Dados do cliente. **propriedades** **id** `string` ID do cliente. **name** `string` Nome do cliente. **email** `string` E-mail do cliente. **merchant** `object` Dados do merchant dono da assinatura. **propriedades** **id** `string` ID do merchant. **tradeName** `string` Nome fantasia do merchant. Ex.: `Loja Exemplo`. **charges** `object[]` Histórico de tentativas de cobrança da assinatura. Há uma linha por tentativa: as retentativas recusadas de um ciclo repetem o mesmo `billingCycle`. A lista vem ordenada por `billingCycle` decrescente (o ciclo mais recente primeiro). **propriedades** **id** `string` ID do **registro de cobrança da assinatura**, o mesmo valor de `data.charge.id` nos webhooks de assinatura. Não é o id usado em `GET /v1/charges/{id}`. **billingCycle** `integer` Número do ciclo de cobrança. `0` é a cobrança do trial pago. Ex.: `1`. **billingPeriodStart** `string` Início do período cobrado (formato `date-time`). **billingPeriodEnd** `string` Fim do período cobrado (formato `date-time`). **amount** `number` Valor cobrado, em reais. Ex.: `99.9`. **currency** `string` Código da moeda. Ex.: `BRL`. **status** `string` Status da tentativa: `pending` (em análise), `paid` (paga), `failed` (falhou) ou `refunded` (estornada). **pspTransactionId** `string | null` ID da transação no processador (PSP). Ex.: `12345`. **failureReason** `string | null` Motivo da falha, quando houver. **createdAt** `string` Data da cobrança (formato `date-time`). **metadata** `object | null` Informações suas guardadas na assinatura. Ex.: `{"referralCode": "PROMO2024"}`. ### Onde obter o id da cobrança `charges[].id` não serve em `GET /v1/charges/{id}`. O id da cobrança (o mesmo dos webhooks `charge.*`) aparece hoje em: | Onde | Campo | | - | - | | Resposta de [Criar assinatura](/referencia/assinaturas/criar) | `firstCharge.chargeId` e `trialCharge.chargeId` | | Webhooks de assinatura | `data.charge.charge_id` (o `data.charge.id` é o registro, igual a `charges[].id` desta rota) | | Listagem de cobranças do plano, `GET /v1/subscription-plans/{id}/charges` | `data[].chargeId`. Cada item traz também `id` (o registro), `subscriptionId` e `billingCycle`, o que permite relacionar o registro desta rota à cobrança. `chargeId` vem `null` quando a tentativa nem chegou ao processador (por exemplo, cartão indisponível) | A listagem de cobranças do plano exige a mesma permissão desta rota (visualizar assinaturas). | HTTP | Significado | Corpo | | - | - | - | | `200` | Assinatura encontrada | Objeto da assinatura com `charges` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão visualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Assinatura não encontrada | `{"statusCode": 404, "message": "Subscription not found"}` | > [!NOTE] > > **Para o negócio:** o `plan.price` mostra o preço do plano e o `charges[].amount` mostra o que de fato foi cobrado em cada ciclo. Como editar um plano não muda assinaturas existentes, use o histórico de `charges` para responder ao cliente quanto ele paga. O `failureReason` é um texto descritivo, útil para o atendimento explicar uma recusa. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` "Subscription not found" | `id` errado, de outra conta, ou id de plano ou cobrança no lugar do id da assinatura | Use o `id` devolvido na criação ou o `data.id` do webhook | | `GET /v1/charges/{id}` não encontra a cobrança de um ciclo | Foi usado `charges[].id`, que é o registro da assinatura | Use o `chargeId` (veja [Onde obter o id da cobrança](#onde-obter-o-id-da-cobrança)) | | O mesmo ciclo aparece mais de uma vez em `charges` | Cada retentativa recusada gera uma linha com o mesmo `billingCycle` | Considere a linha com `status` `paid` do ciclo, se houver | | `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão visualizar assinaturas (ex.: Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Acesso cortado cedo demais após cancelamento regular | O `status` vira `cancelled` assim que a assinatura é cancelada | No cancelamento regular, mantenha o acesso até o `accessRevokedAt` devolvido pelo cancelamento | ```http REST (JSON) theme={null} GET /v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q', { headers: { Authorization: `Basic ${credentials}` } }, ); const subscription = await response.json(); const ultimaTentativa = subscription.charges[0]; // lista em ordem decrescente de billingCycle ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "active", "currentPeriodStart": "2024-01-15T10:30:00.000Z", "currentPeriodEnd": "2024-02-15T10:30:00.000Z", "cancelledAt": null, "cancellationType": null, "refunded": false, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z", "plan": { "id": "2RhQg9M7ZCg3X3nMb9W2kY9R", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly" }, "customer": { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "name": "Joao Silva", "email": "joao@email.com" }, "merchant": { "id": "2Mk4pTq8RwZ1yVb6NcX3sLd7Hf9", "tradeName": "Loja Exemplo" }, "charges": [ { "id": "3Fh8nQ2wLr5tYb7cXz9VkP4mJd1", "billingCycle": 1, "billingPeriodStart": "2024-01-15T10:30:00.000Z", "billingPeriodEnd": "2024-02-15T10:30:00.000Z", "amount": 99.9, "currency": "BRL", "status": "paid", "pspTransactionId": "12345", "failureReason": null, "createdAt": "2024-01-15T10:30:00.000Z" } ], "metadata": { "referralCode": "PROMO2024" } } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Subscription not found" } ``` ## Veja também > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos e correlação com os webhooks de cobrança. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Cancelar assinatura](/referencia/assinaturas/cancelar) > > Cancelamento com ou sem estorno. # Criar uma assinatura Source: https://docs.fastpaybrasil.com/referencia/assinaturas/criar POST /v1/subscriptions Vincula um cliente a um plano, registra ou reutiliza o cartão e processa a primeira cobrança da assinatura. Esta é a rota do checkout de assinatura. Com ela você liga um **cliente** a um **plano** e define o **cartão** que será cobrado automaticamente a cada ciclo, sem que o cliente precise digitar o CVV de novo. A primeira cobrança (ou a validação do cartão, no trial grátis) acontece na própria chamada, e as renovações seguintes ficam por conta da Finvia. ## Quando usar | Situação | Como usar esta rota | | - | - | | Cliente já cadastrado com cartão salvo (fluxo recomendado) | `customerId` + `cardTokenId` | | Cliente já cadastrado digitando o cartão no checkout | `customerId` + `paymentMethod` | | Cliente novo no checkout | Objeto `customer` (com `document`) + `paymentMethod` | | Plano com trial, mas o cliente quer começar pagando | `skipTrial: true` | | Guardar dados seus na assinatura (campanha, ID interno) | `metadata` | | Venda avulsa ou recompra com o cliente presente | Use [Criar cobrança](/referencia/cobrancas/criar) | | Trocar cartão ou plano de uma assinatura | Não existe troca. Cancele a assinatura e crie outra por esta rota | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **criar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Tenha um plano **ativo** ([Criar plano](/referencia/planos/criar), [Consultar plano](/referencia/planos/consultar)). Plano inexistente ou inativo devolve `404`. * O cliente precisa ter **e-mail** e **CPF ou CNPJ** quando o cartão é cadastrado nesta chamada (cartão em `paymentMethod`). O tipo do documento é deduzido pela quantidade de dígitos: 11 é CPF, 14 é CNPJ. Qualquer outro tamanho (passaporte, RG) conta como cliente sem documento. * No fluxo recomendado, registre antes o cartão em [Registrar cartão](/referencia/cartoes/registrar). O cartão precisa pertencer ao mesmo merchant da chave usada. Com `cardTokenId`, o cartão já está cadastrado e não há nova checagem de documento. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste, inclusive a validação de R\$ 1,00 do trial grátis. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). ## O que acontece no checkout **1. Validação do plano** O plano informado em `subscriptionPlanId` precisa existir e estar ativo. **2. Cliente** Com `customerId`, o cliente existente é usado. Com o objeto `customer`, a Finvia localiza o cliente pelo e-mail ou cria um novo. Se o cliente já existe, vale o documento do cadastro, e não o enviado na requisição. **3. Cartão** Com `paymentMethod`, o cartão é registrado no cofre da Finvia e nasce `active`. Sem e-mail ou sem CPF/CNPJ no cliente, a resposta é `400` e a assinatura não é criada. Com `cardTokenId`, o cartão já registrado é usado. **4. Validação do trial grátis** Só em plano com trial grátis e sem `skipTrial: true`: a Finvia cobra R\$ 1,00 e estorna em seguida (o estorno é assíncrono). Se essa cobrança for recusada, ficar em análise ou o processador não responder, a resposta é `422 CARD_VALIDATION_FAILED` e nada é criado: nem assinatura, nem webhook. Nos demais planos, a própria primeira cobrança valida o cartão. **5. Primeira cobrança** A cobrança acontece na criação da assinatura: sem trial, cobra o valor cheio; com trial pago, cobra o valor do trial; com `skipTrial: true`, cobra o valor cheio. **6. Assinatura criada** Se a cobrança for aprovada, a assinatura fica `active`. Se for recusada ou ficar em análise, fica `pending_activation`. O ciclo fica ancorado na data e hora da contratação (ou no fim do trial, em planos com trial). ## Corpo da requisição Campo obrigatório: `subscriptionPlanId`. Informe também o cliente (`customerId` **ou** `customer`) e o cartão (`cardTokenId` **ou** `paymentMethod`). **subscriptionPlanId** `string` *required* ID do plano de assinatura. Ex.: `2RhQg9M7ZCg3X3nMb9W2kY9R`. > [!NOTE] > > Não há como escolher o dia de cobrança. O ciclo é ancorado na data e hora da contratação, ou no fim do trial. Um campo `billingDay` enviado é ignorado, sem erro e sem efeito. As regras de renovação estão em [Ciclo de vida](/guias/assinaturas/ciclo-de-vida). **customerId** `string` ID de um cliente já cadastrado. Use este campo **ou** o objeto `customer`, nunca os dois. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **customer** `object` Dados do cliente. Use este objeto **ou** `customerId`, nunca os dois. A Finvia procura o cliente pelo e-mail e, se não encontrar, cria um novo. **propriedades** **name** `string` *required* Nome do cliente. Ex.: `Joao Silva`. **email** `string` *required* E-mail do cliente (formato `email`). Ex.: `joao@email.com`. **document** `object` Documento do cliente. Obrigatório quando o cartão vai em `paymentMethod`. Se já existir na conta um cliente com o mesmo e-mail, vale o documento desse cadastro, e não o desta requisição. **propriedades** **type** `string` Tipo do documento: `cpf` ou `cnpj`. O tipo efetivo é deduzido pela quantidade de dígitos de `id`, e não por este campo. **id** `string` CPF (11 dígitos) ou CNPJ (14 dígitos). A pontuação é aceita e removida. Qualquer outro tamanho conta como cliente sem documento. Ex.: `52998224725`. **phoneNumber** `string` Telefone do cliente. Ex.: `+5511987654321`. **cardTokenId** `string` ID de um cartão já registrado em [Registrar cartão](/referencia/cartoes/registrar), pela mesma conta. Use este campo **ou** `paymentMethod`, nunca os dois. As cobranças da assinatura não pedem CVV. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. **paymentMethod** `object` Dados de um cartão novo, que é registrado junto com a assinatura. Use este objeto **ou** `cardTokenId`, nunca os dois. **propriedades** **number** `string` *required* Número do cartão. Ex.: `4111111111111111`. **holderName** `string` *required* Nome impresso no cartão. Ex.: `JOAO SILVA`. **expirationMonth** `string` *required* Mês de validade, de `01` a `12`, com 2 caracteres (`minLength` 2, `maxLength` 2). Ex.: `12`. **expirationYear** `string` *required* Ano de validade no formato `YYYY`, com 4 caracteres (`minLength` 4, `maxLength` 4). Ex.: `2028`. **cvv** `string` *required* Código de segurança. Mínimo de 3 caracteres. Ex.: `123`. **validateCard** `boolean` *deprecated* Obsoleto. O campo é aceito, mas não tem efeito: o cartão nasce `active`, sem transação de teste e sem etapa de ativação. A única validação extra é a de R\$ 1,00 do trial grátis, que não depende deste campo. **skipTrial** `boolean` Quando `true`, ignora o trial do plano (se houver) e cobra o valor cheio na criação da assinatura. O padrão é `false`. **metadata** `object` Informações suas, em formato livre, guardadas na assinatura. Ex.: `{"referralCode": "PROMO2024"}`. > [!NOTE] > > **Para o negócio:** no trial grátis, o comprador pode ver na fatura do cartão duas linhas de R\$ 1,00 (a cobrança de validação e o estorno). Avise isso no checkout. Se a mesma requisição (mesmo merchant, cliente, cartão e plano) for reenviada em até 15 minutos, a API reaproveita a validação aprovada e não cobra o R\$ 1,00 de novo. ## Respostas **id** `string` Identificador único da assinatura. Guarde este valor: ele é usado para consultar, atualizar, cancelar e conciliar com os webhooks (`data.id` nos eventos `subscription.*`). **status** `string` Situação da assinatura: | Valor | Significado | | - | - | | `active` | Assinatura ativa e cobrando normalmente | | `pending_activation` | A primeira cobrança foi recusada ou está em análise. A assinatura não está ativa, não cobra, não renova e não tem retentativa automática. Se a análise aprovar o pagamento, passa a `active` automaticamente | Na criação, só esses dois status são possíveis. ### Assinatura em `pending_activation` A API não tenta de novo a primeira cobrança, e [Atualizar assinatura](/referencia/assinaturas/atualizar) só aceita assinaturas `active`. A assinatura só sai desse status sozinha em um caso: a primeira cobrança (ou a do trial pago) ficou em análise (`firstCharge.pending: true` ou `trialCharge.pending: true`) e a análise aprovou. Aí ela passa a `active` e o webhook `subscription.activated` é enviado. Se a análise recusar, chega `subscription.payment_failed` e a assinatura continua `pending_activation`. Para tentar de novo (por exemplo, com outro cartão), crie uma **nova** assinatura por esta rota. A API não reaproveita a pendente: a nova assinatura tem outro `id`. Cancele a pendente em [Cancelar assinatura](/referencia/assinaturas/cancelar) para que ela não fique na listagem; enquanto estiver pendente, ela não cobra nada. **cardTokenId** `string` ID do cartão registrado usado na assinatura. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. **currentPeriodStart** `string` Início do período de cobrança atual (formato `date-time`). **currentPeriodEnd** `string` Fim do período de cobrança atual (formato `date-time`). **cardValidation** `object` Só em plano com trial grátis (sem `skipTrial`). Resultado da validação de R\$ 1,00. **propriedades** **validated** `boolean` `true` quando a validação foi aprovada. **amount** `number` Valor da validação, em reais. Ex.: `1`. **firstCharge** `object | null` Resultado da primeira cobrança. **propriedades** **success** `boolean` `true` quando a cobrança foi aprovada. **pending** `boolean` `true` quando o pagamento está **em análise** no processador. Não crie outra assinatura: aguarde o webhook `subscription.activated` (aprovado) ou `subscription.payment_failed` (recusado). **chargeId** `string` Id da cobrança, o mesmo usado em `GET /v1/charges/{id}` e nos webhooks `charge.*`. Guarde este valor: [Consultar assinatura](/referencia/assinaturas/consultar) não o devolve. **nsuOperacao** `string` Identificador da operação no processador (PSP). Ex.: `123456789`. **codigoAutorizacao** `string` Código de autorização. Ex.: `ABC123`. **message** `string` Mensagem do resultado. Ex.: `Transaction approved`. **trialCharge** `object | null` Resultado da cobrança do trial pago. Traz os mesmos campos de `firstCharge`, inclusive `success`, `pending` e `chargeId`. | HTTP | Significado | Corpo | | - | - | - | | `201` | Assinatura criada | `id`, `status`, `cardTokenId`, `currentPeriodStart`, `currentPeriodEnd`, `firstCharge` e, conforme o plano, `trialCharge` e `cardValidation` | | `400` | Cliente sem e-mail ou sem CPF/CNPJ ao cadastrar o cartão | `{"statusCode": 400, "message": "Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador"}` | | `400` | Dados inválidos ou falha na criação | `{"statusCode": 400, "message": "Failed to create subscription"}` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão criar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Plano não encontrado ou inativo | `{"statusCode": 404, "message": "Subscription plan not found or inactive"}` | | `409` | Já há uma validação do mesmo cartão em andamento (requisição repetida em paralelo) | `{"code": "CARD_VALIDATION_IN_PROGRESS", "message": "..."}` | | `422` | Validação de R\$ 1,00 do trial grátis recusada, em análise ou sem resposta do processador | `{"code": "CARD_VALIDATION_FAILED", "message": "Não foi possível validar o cartão: "}` | | `429` | 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na mesma conta em 1 hora | `{"code": "CARD_VALIDATION_RATE_LIMITED", "message": "..."}` | ### Erros da validação do trial grátis Os erros `409`, `422` e `429` têm o formato `{ code, message }`, sem `statusCode`. Decida o fluxo pelo `code` e use a `message` só para exibir. No `422`, o `` é texto livre: pode ser o motivo devolvido pelo processador, `pagamento em análise. Use outro cartão.`, `cobrança recusada.` ou `processador indisponível.`. Nesses casos nada é criado: nem assinatura, nem webhook. > [!NOTE] > > **Para o negócio:** a primeira cobrança acontece na criação da assinatura. Se ela for recusada, a assinatura fica `pending_activation`, não cobra e não renova: o checkout deve oferecer em seguida outro cartão, criando uma nova assinatura. Depois de ativa, as renovações são feitas por uma rotina que roda às 6h, 12h e 18h (horário de Brasília), com retentativas em caso de recusa. Os detalhes estão em [Ciclo de vida](/guias/assinaturas/ciclo-de-vida). ## Exemplos por caso de uso > [tab] Cartão salvo (recomendado) > > Cliente e cartão já cadastrados. O cartão foi registrado em `POST /v1/cards` e nasceu `active`. > > ```json theme={null} > { > "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", > "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", > "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo" > } > ``` > [tab] Cartão digitado no checkout > > Cliente já cadastrado, cartão novo informado na própria chamada. > > ```json theme={null} > { > "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", > "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", > "paymentMethod": { > "number": "4111111111111111", > "holderName": "JOAO SILVA", > "expirationMonth": "12", > "expirationYear": "2028", > "cvv": "123" > } > } > ``` > [tab] Cliente novo > > Primeiro acesso do cliente. A Finvia procura pelo e-mail e cria o cadastro se não existir. > > ```json theme={null} > { > "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", > "customer": { > "name": "Joao Silva", > "email": "joao@email.com", > "document": { "type": "cpf", "id": "52998224725" }, > "phoneNumber": "+5511987654321" > }, > "paymentMethod": { > "number": "4111111111111111", > "holderName": "JOAO SILVA", > "expirationMonth": "12", > "expirationYear": "2028", > "cvv": "123" > }, > "metadata": { "referralCode": "PROMO2024" } > } > ``` > [tab] Pular o trial > > Plano com trial, mas o cliente quer começar já no plano pago. > > ```json theme={null} > { > "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", > "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", > "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", > "skipTrial": true > } > ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` "Subscription plan not found or inactive" | Plano inexistente, de outra conta ou `inactive` | Confira o plano em [Consultar plano](/referencia/planos/consultar) | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão criar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | `400` "Failed to create subscription" | Dados inválidos ou falha na criação | Revise o corpo: cliente e cartão informados uma vez cada, campos do cartão completos | | Cobrança real feita com a chave de teste | Assinaturas não têm modo de teste | Homologue com cartão real de valor baixo e cancele em até 7 dias para que as cobranças pagas sejam estornadas | | `400` com `O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 nem 14 dígitos | Informe e-mail e CPF ou CNPJ | | Mesmo erro de documento, com CPF na requisição | Já existe um cliente com o mesmo e-mail, cadastrado com outro documento. Vale o documento do cadastro | Crie um cliente com e-mail e CPF ou CNPJ e envie o `customerId` dele | | `cardTokenId` rejeitado | Cartão registrado por outro merchant ou subconta | Registre o cartão com a mesma chave usada para criar a assinatura | | `422 CARD_VALIDATION_FAILED` | Validação de R\$ 1,00 do trial grátis recusada, em análise ou sem resposta do processador | Peça outro cartão ao comprador | | `409 CARD_VALIDATION_IN_PROGRESS` | A mesma requisição foi enviada em paralelo | Aguarde a resposta da primeira chamada antes de reenviar | | `429 CARD_VALIDATION_RATE_LIMITED` | Recusas demais do mesmo cartão (3 em 24 horas) ou da conta (30 em 1 hora) | Peça outro cartão e revise o fluxo de checkout que está gerando as tentativas | | `status` `pending_activation` | Primeira cobrança recusada ou em análise | Se em análise (`firstCharge.pending: true`), aguarde os webhooks. Se recusada, crie uma nova assinatura com outro cartão e cancele a pendente | | Assinatura duplicada após timeout | Reenvio sem verificar se a primeira foi criada | A API não suporta `Idempotency-Key`. Liste as assinaturas do cliente com `customerId` antes de reenviar | ```http REST (JSON) theme={null} POST /v1/subscriptions HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/subscriptions', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ subscriptionPlanId: '2RhQg9M7ZCg3X3nMb9W2kY9R', customerId: '2vorkDcXyvzifL63YX09S9VqcnI', cardTokenId: '36OO3bcGjhPjjF3tzrqOGcmQuKo', metadata: { internalUserId: '12345' }, }), }); const subscription = await response.json(); if (subscription.status === 'pending_activation') { // primeira cobrança recusada ou em análise: não libere o acesso ainda } ``` ```python Python theme={null} import os import requests payload = { "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/subscriptions", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2RhQg9M7ZCg3X3nMb9W2kY9R', 'customerId' => '2vorkDcXyvzifL63YX09S9VqcnI', 'cardTokenId' => '36OO3bcGjhPjjF3tzrqOGcmQuKo', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscriptions'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscriptions")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscriptions"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId": "2vorkDcXyvzifL63YX09S9VqcnI", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/subscriptions", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscriptions") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "subscriptionPlanId" => "2RhQg9M7ZCg3X3nMb9W2kY9R", "customerId" => "2vorkDcXyvzifL63YX09S9VqcnI", "cardTokenId" => "36OO3bcGjhPjjF3tzrqOGcmQuKo", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "active", "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "currentPeriodStart": "2024-01-15T10:30:00.000Z", "currentPeriodEnd": "2024-02-15T10:30:00.000Z", "firstCharge": { "success": true, "chargeId": "2xKp7QmR4tVw9YzA1bC3dE5fG6h", "nsuOperacao": "123456789", "codigoAutorizacao": "ABC123", "message": "Transaction approved" } } ``` ```json 422 theme={null} { "code": "CARD_VALIDATION_FAILED", "message": "Não foi possível validar o cartão: cobrança recusada." } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Subscription plan not found or inactive" } ``` ```json 400 theme={null} { "statusCode": 400, "message": "Failed to create subscription" } ``` ## Veja também > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > `subscription.created`, `subscription.activated` e demais eventos. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Homologação](/homologacao/roteiro) > > Cenários SUB-01 a SUB-06. # Listar assinaturas Source: https://docs.fastpaybrasil.com/referencia/assinaturas/listar GET /v1/subscriptions Lista as assinaturas da sua conta, com filtros por cliente, status e busca por nome, e-mail ou plano. Esta rota devolve as assinaturas cadastradas, página por página, com um resumo do plano e do cliente de cada uma. Ela atende o painel interno do seu time (quem está ativo, quem cancelou, quem expirou) e a área "Minha assinatura" do cliente, filtrando pelo `customerId`. ## Quando usar | Situação | Como usar esta rota | | - | - | | Painel de assinantes ativos | `status=active` | | Ação de recuperação de clientes que saíram | `status=expired` ou `status=cancelled` | | Área do cliente com as assinaturas dele | `customerId` | | Atendimento procurando um assinante | `search` com nome, e-mail do cliente ou nome do plano | | Conferir se a assinatura já foi criada depois de um timeout | `customerId` e confira `createdAt` | | Histórico de cobranças de uma assinatura | Use [Consultar assinatura](/referencia/assinaturas/consultar) | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **visualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager**, **Operador** e **Visualizador**. Os perfis Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * O tamanho da página vai em `size` ([Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia)). > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). ## Parâmetros de consulta **merchantId** `string` Filtra pelas assinaturas de um merchant específico. **customerId** `string` Filtra pelas assinaturas de um cliente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **status** `string` Filtra pelo status da assinatura: `pending_activation`, `active`, `cancelled` ou `expired`. **search** `string` Busca por nome ou e-mail do cliente, ou pelo nome do plano. Ex.: `joao`. **page** `integer` (default: 1) Número da página. A contagem começa em `1`. **size** `integer` (default: 10) Quantidade de assinaturas por página. ## Respostas **data** `object[]` Assinaturas da página atual. **propriedades** **id** `string` Identificador único da assinatura. **status** `string` Status da assinatura: | Valor | Significado | | - | - | | `pending_activation` | A primeira cobrança foi recusada ou está em análise. A assinatura não está ativa, não cobra, não renova e não tem retentativa automática. Se a análise aprovar o pagamento, passa a `active` automaticamente | | `active` | Ativa e em dia. Continua `active` durante as retentativas de cobrança | | `cancelled` | Cancelada | | `expired` | Encerrada: limite de retentativas esgotado ou o plano chegou ao `endDate` | **currentPeriodStart** `string | null` Início do período de cobrança atual (formato `date-time`). **currentPeriodEnd** `string | null` Fim do período de cobrança atual (formato `date-time`). **cancelledAt** `string | null` Data do cancelamento (formato `date-time`). `null` se não foi cancelada. **cancellationType** `string | null` Tipo de cancelamento: `regret` (arrependimento, até 7 dias da criação) ou `regular` (depois de 7 dias). `null` se não foi cancelada. **refunded** `boolean` `true` quando havia cobranças pagas e todas foram estornadas (cancelamento por arrependimento). `false` no cancelamento regular, no arrependimento sem cobrança paga (ex.: trial grátis) ou quando um estorno não foi concluído. **createdAt** `string` Data de criação (formato `date-time`). **updatedAt** `string` Data da última atualização (formato `date-time`). **plan** `object` Resumo do plano. **propriedades** **name** `string` Nome do plano. Ex.: `Plano Premium Mensal`. **price** `number` Preço do plano, em reais. Ex.: `99.9`. **currency** `string` Código da moeda. Ex.: `BRL`. **customer** `object` Resumo do cliente. **propriedades** **name** `string` Nome do cliente. **email** `string` E-mail do cliente. **meta** `object` Dados da paginação. **propriedades** **total** `integer` Total de assinaturas encontradas. Ex.: `100`. **page** `integer` Página atual. Ex.: `1`. **limit** `integer` Itens por página. Ex.: `10`. **totalPages** `integer` Total de páginas. Ex.: `10`. | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista devolvida | `data` e `meta` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão visualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | > [!NOTE] > > **Para o negócio:** a listagem mostra o retrato atual da base. Uma assinatura com cobrança de renovação falhando continua `active` enquanto houver retentativas; ela só vira `expired` quando o limite de tentativas do ciclo se esgota (veja [Ciclo de vida](/guias/assinaturas/ciclo-de-vida)). Para agir antes disso, como avisar o cliente de que o pagamento falhou (a troca de cartão exige cancelar e criar outra assinatura), use o webhook `subscription.payment_failed`, enviado a cada tentativa que falha. > [!TIP] > > **Para o desenvolvedor:** a listagem traz só o resumo de plano e cliente (sem IDs) e não inclui `metadata` nem o histórico de cobranças. Para esses dados, chame [Consultar assinatura](/referencia/assinaturas/consultar) com o `id`. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão visualizar assinaturas (ex.: Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Lista vem com 10 itens mesmo enviando `limit` | O parâmetro de tamanho é `size` | Envie `size` | | Cliente com cobrança recusada aparece como `active` | Retentativas ainda pendentes | Comportamento esperado. Acompanhe `subscription.payment_failed` | ```http REST (JSON) theme={null} GET /v1/subscriptions?status=active&page=1&size=10 HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions?status=active&page=1&size=10" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const params = new URLSearchParams({ customerId: '2RhQg9M7ZCg3X3nMb9W1kX8Q', page: '1', size: '10' }); const response = await fetch(`https://api-global.fastpaybrasil.com/v1/subscriptions?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); const { data, meta } = await response.json(); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/subscriptions?status=active&page=1&size=10", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscriptions?status=active&page=1&size=10")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/subscriptions?status=active&page=1&size=10"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/subscriptions?status=active&page=1&size=10", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscriptions?status=active&page=1&size=10") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "data": [ { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "status": "active", "currentPeriodStart": "2024-01-15T10:30:00.000Z", "currentPeriodEnd": "2024-02-15T10:30:00.000Z", "cancelledAt": null, "cancellationType": null, "refunded": false, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z", "plan": { "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL" }, "customer": { "name": "Joao Silva", "email": "joao@email.com" } } ], "meta": { "total": 100, "page": 1, "limit": 10, "totalPages": 10 } } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## Veja também > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Consultar assinatura](/referencia/assinaturas/consultar) > > Detalhes e histórico de cobranças. # Consultar saldos (carteiras) Source: https://docs.fastpaybrasil.com/referencia/carteiras/listar GET /v1/wallets Devolve as carteiras de um merchant, uma por moeda, com saldo disponível, pendente e reservado e o equivalente em dólar. Cada merchant tem uma carteira (wallet) por moeda. Esta rota devolve essas carteiras com três saldos: disponível (`available`), pendente (`pending`) e reservado (`reserved`). Ela também informa se o saque está habilitado em cada moeda e traz os mesmos saldos convertidos para dólar. ## Quando usar | Situação | Como usar esta rota | | - | - | | Mostrar o saldo no seu painel | Consulte com o `merchantId` da conta | | Conferir se há saldo antes de pedir um saque | Leia `balance.available` e `isWithdrawalEnabled` da moeda desejada | | Acompanhar o saldo de cada subconta em um marketplace | Consulte com o `merchantId` de cada subconta | | Ver só uma moeda | Envie `currency`, por exemplo `BRL` | | Ver o valor de cada venda | Use [`GET /v1/charges`](/referencia/cobrancas/listar). Esta rota mostra só os totais | ## Antes de chamar * Use a chave secreta (`sk_`) em Basic, como no resto da API ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * A chave age com as permissões do usuário que a gerou. A chave padrão da conta pertence ao proprietário e funciona aqui. Uma chave gerada por um usuário com o perfil **Desenvolvedor** recebe `403` `Acesso negado` nesta rota. * Tenha o `merchantId` da conta que você quer consultar: a sua própria conta ou, para a conta master do Connect, uma subconta. ## Parâmetros de consulta **merchantId** `string` *required* ID do merchant cujas carteiras você quer consultar. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **currency** `string` Filtra pela moeda da carteira (código ISO 4217). Ex.: `BRL`. ## Respostas A resposta `200` é um **array** de carteiras, sem paginação. Cada item tem os campos abaixo. **currency** `string` Moeda da carteira. Ex.: `BRL`. **isWithdrawalEnabled** `boolean` Indica se o saque está habilitado nesta moeda. Ex.: `true`. **balance** `object` Saldos na moeda da carteira. **propriedades** **available** `number` Saldo disponível. Ex.: `1000.5`. **pending** `number` Saldo pendente. Ex.: `250`. **reserved** `number` Saldo reservado. Ex.: `100`. **usdBalance** `object` Os mesmos saldos convertidos para dólar (USD). **propriedades** **available** `number` Saldo disponível em USD. Ex.: `200.1`. **pending** `number` Saldo pendente em USD. Ex.: `50`. **reserved** `number` Saldo reservado em USD. Ex.: `20`. > [!NOTE] > > O contrato não detalha as regras que movem o valor de `pending` para `available` nem o que leva um valor a `reserved`. Para essas regras, consulte o guia de [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento) e o seu contato comercial. > [!NOTE] > > **Para o negócio:** os valores estão em **reais** (na unidade da moeda): `1000.5` significa R\$ 1.000,50. Antes de pedir um saque, confira duas coisas na carteira da moeda: se `isWithdrawalEnabled` é `true` e se `balance.available` cobre o valor. | HTTP | Significado | Corpo | | - | - | - | | `200` | Carteiras obtidas | Array de carteiras | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Usuário dono da chave sem permissão de saldo (ex.: perfil Desenvolvedor) | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` | | `404` | Merchant inexistente ou fora do acesso da credencial | `{"statusCode": 404, "message": "Merchant not found", "error": "Not Found"}` | Trate o erro pelo código HTTP, não pelo texto da mensagem. ## Exemplos por caso de uso > [tab] Saldo em reais > > Consulta só a carteira em BRL, para mostrar no painel. > > ```bash theme={null} > curl -X GET "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI¤cy=BRL" \ > -u "$FINVIA_API_KEY:" > ``` > [tab] Checar antes do saque > > ```javascript theme={null} > const wallets = await consultarCarteiras(merchantId, 'BRL'); > const brl = wallets.find((w) => w.currency === 'BRL'); > > const valorDoSaque = 500; // R$ 500,00 > const podeSacar = brl && brl.isWithdrawalEnabled && brl.balance.available >= valorDoSaque; > ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` `Acesso negado` | A chave foi gerada por um usuário com perfil Desenvolvedor | Use a chave padrão da conta ou gere uma com usuário Owner ou Manager | | `404` | `merchantId` inexistente ou fora do seu acesso | Confira o ID do merchant | | Esperava paginação | A rota devolve um array simples | Leia a resposta como lista, sem `page` | | Lista vazia ao filtrar por moeda | Não há carteira nessa moeda | Consulte sem `currency` para ver todas as carteiras | ## Como testar O cenário **PAY-01** do [Roteiro de homologação](/homologacao/roteiro) pede a consulta do saldo disponível por moeda antes do saque. A consulta funciona com a chave de teste, mas o saque não: não existe saque no Modo Teste. ```http REST (JSON) theme={null} GET /v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI¤cy=BRL HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI¤cy=BRL" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const params = new URLSearchParams({ merchantId: '2vorkDcXyvzifL63YX09S9VqcnI', currency: 'BRL' }); const response = await fetch(`https://api-global.fastpaybrasil.com/v1/wallets?${params}`, { headers: { Authorization: `Basic ${auth}` }, }); const wallets = await response.json(); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI¤cy=BRL", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI¤cy=BRL")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI¤cy=BRL"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI¤cy=BRL", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI¤cy=BRL") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} [ { "currency": "BRL", "isWithdrawalEnabled": true, "balance": { "available": 1000.5, "pending": 250, "reserved": 100 }, "usdBalance": { "available": 200.1, "pending": 50, "reserved": 20 } } ] ``` ```json 404 theme={null} { "statusCode": 404, "message": "Merchant not found", "error": "Not Found" } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## Veja também > [card] [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento) > > Como acompanhar saldo e sacar. > [card] [Solicitar saque](/referencia/saques/criar) > > Saque do saldo da própria conta, por Pix. > [card] [Meios de pagamento](/referencia/meios-de-pagamento/listar) > > Formas de pagamento disponíveis na conta. > [card] [Criar saque da subconta](/referencia/fast-connect/criar-saque) > > Saque de subconta pela conta master. # Consultar um cartão Source: https://docs.fastpaybrasil.com/referencia/cartoes/consultar GET /v1/cards/{id} Devolve os dados de um cartão salvo no cofre, incluindo a situação dele. Esta rota devolve os detalhes de um cartão salvo: número mascarado, bandeira, validade e `status`. O `status` desta rota pode mostrar duas coisas diferentes, conforme o cartão: o cadastro do cartão na adquirente ou a situação dele no cofre (detalhes abaixo). > [!WARNING] > > Hoje esta consulta pode mostrar `active` para um cartão já excluído ou vencido. Para decidir se um cartão pode ser usado em [`POST /v1/charges`](/referencia/cobrancas/criar), use [Listar cartões](/referencia/cartoes/listar) com `customerId`: a cobrança recusa cartão `revoked` ou `expired`, e a listagem mostra essa situação corretamente. ## Quando usar | Situação | Como usar esta rota | | - | - | | Mostrar ao cliente qual cartão está cadastrado | Use `maskedNumber`, `brand`, `expirationMonth` e `expirationYear` | | Saber se o cartão ficou sem assinatura | `status` `inactive` indica que a assinatura que usava o cartão foi cancelada e nenhuma outra o usa | | Conferir se o cartão pode ser cobrado | Use [Listar cartões](/referencia/cartoes/listar) com `customerId` (veja o aviso acima) | | Ver todos os cartões de um cliente | Use [Listar cartões](/referencia/cartoes/listar) com `customerId` | ## Antes de chamar * Tenha uma chave secreta (`sk_`) da conta que registrou o cartão ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Tenha o `id` do cartão (devolvido por [Registrar cartão](/referencia/cartoes/registrar)). ## Parâmetros de caminho **id** `string` *required* Identificador único do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Respostas **id** `string` ID do token do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **token** `string` Token do cartão. Ex.: `tok_abc123xyz`. **maskedNumber** `string | null` Número mascarado do cartão. Ex.: `****1111`. **brand** `string` Bandeira do cartão. Ex.: `visa`. **expirationMonth** `string` Mês de validade. Ex.: `12`. **expirationYear** `string` Ano de validade. Ex.: `2028`. **status** `string` Situação do cartão: `active`, `inactive`, `pending_validation`, `expired` ou `revoked`. Quando o cartão tem cadastro na adquirente, o valor mostra esse cadastro (`active`, `inactive` ou `pending_validation`). Só quando não há esse cadastro a rota mostra a situação no cofre (`active`, `expired` ou `revoked`). **createdAt** `string` Data e hora de criação (formato `date-time`). Ex.: `2024-01-15T10:30:00.000Z`. | `status` | O que significa | | - | - | | `active` | Cartão ativo | | `inactive` | A assinatura que usava o cartão foi cancelada e nenhuma outra o usa. Volta a `active` se o cliente assinar de novo com esse cartão | | `pending_validation` | Aparece só em cartões antigos, registrados com o processador anterior | | `expired` | Validade vencida (situação no cofre) | | `revoked` | Cartão excluído com [`DELETE /v1/cards/{id}`](/referencia/cartoes/excluir) (situação no cofre) | | HTTP | Significado | Corpo | | - | - | - | | `200` | Cartão encontrado | Dados do cartão | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `404` | Cartão não encontrado | `{"statusCode": 404, "message": "Card not found"}` | > [!NOTE] > > **Para o negócio:** quando o cartão de um assinante vence ou é recusado na renovação, não existe troca de cartão na assinatura. O caminho é registrar o cartão novo, cancelar a assinatura e criar outra. Consultar o `status` ajuda o atendimento a explicar ao cliente o que aconteceu. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` com `Card not found` | `id` incorreto ou cartão registrado por outra conta | Confira o `id` e use a chave da conta que registrou o cartão | | Cobrança com cartão salvo falha, mas a consulta mostra `active` | A consulta pode mostrar `active` para cartão excluído ou vencido | Confira o cartão em [Listar cartões](/referencia/cartoes/listar) com `customerId` e peça outro cartão se ele estiver `expired` ou `revoked` | | `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` | ```http REST (JSON) theme={null} GET /v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q', { headers: { Authorization: `Basic ${credentials}` } }, ); const card = await response.json(); console.log(`${card.brand} final ${card.maskedNumber?.slice(-4)}, validade ${card.expirationMonth}/${card.expirationYear}`); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "token": "tok_abc123xyz", "maskedNumber": "****1111", "brand": "visa", "expirationMonth": "12", "expirationYear": "2028", "status": "active", "createdAt": "2024-01-15T10:30:00.000Z" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Card not found" } ``` ## Veja também > [card] [Cofre de cartões](/guias/cofre-de-cartoes) > > Ciclo de vida do cartão salvo. > [card] [Cobrança com cartão salvo](/guias/cobrancas/cartao-salvo) > > Recompra com `cardTokenId`. > [card] [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida) > > Falha de renovação e troca de cartão. > [card] [Listar cartões](/referencia/cartoes/listar) > > Todos os cartões de um cliente. # Excluir um cartão Source: https://docs.fastpaybrasil.com/referencia/cartoes/excluir DELETE /v1/cards/{id} Remove um cartão salvo e revoga o token no cofre da Finvia. Esta rota exclui um cartão salvo. O token é revogado no cofre da Finvia e **não pode mais ser usado** em cobranças nem em assinaturas. Depois da exclusão, o cartão aparece com `status` `revoked` em [Listar cartões](/referencia/cartoes/listar) quando a listagem é feita sem o filtro `customerId`; com o filtro, ele deixa de aparecer. Use quando o cliente remove o cartão da conta dele no seu site ou quando o cartão deixa de ser válido para o seu negócio. ## Quando usar | Situação | Como usar esta rota | | - | - | | Cliente clicou em "remover cartão" na área logada | Exclua pelo `id` do cartão | | Cliente encerrou o cadastro no seu serviço | Exclua os cartões dele (encontre-os em [Listar cartões](/referencia/cartoes/listar)) e depois o [cliente](/referencia/clientes/excluir) | | Troca de cartão de um assinante | Registre o novo cartão, cancele a assinatura e crie outra. Exclua o cartão antigo só depois que a nova assinatura estiver ativa | ## Antes de chamar * Tenha uma chave secreta (`sk_`) da conta que registrou o cartão ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Tenha o `id` do cartão. * Verifique se o cartão está em uso em alguma assinatura ativa. > [!WARNING] > > A exclusão revoga o token: o cartão deixa de poder ser usado em cobranças **e em assinaturas**. Se ele estiver vinculado a uma assinatura ativa, as próximas renovações não poderão usá-lo. Para trocar o cartão de uma assinatura, crie a nova assinatura com o novo cartão antes de excluir o antigo. ## Parâmetros de caminho **id** `string` *required* Identificador único do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. Esta rota não tem corpo de requisição. ## Respostas **id** `string` ID do cartão excluído. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **deleted** `boolean` Confirmação da exclusão. Ex.: `true`. **message** `string` Mensagem de retorno. Ex.: `Card deleted successfully`. | HTTP | Significado | Corpo | | - | - | - | | `200` | Cartão excluído | `id`, `deleted`, `message` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `404` | Cartão não encontrado | `{"statusCode": 404, "message": "Card not found"}` | > [!NOTE] > > **Para o negócio:** oferecer ao cliente a opção de remover o cartão salvo dá a ele controle sobre os próprios dados de pagamento. A remoção é definitiva para aquele token: se o cliente quiser usar o mesmo cartão de novo, ele precisa ser registrado outra vez. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` com `Card not found` | `id` incorreto ou cartão registrado por outra conta | Confira o `id` e use a chave da conta que registrou o cartão | | Renovação de assinatura falha depois da exclusão | O cartão excluído era o cartão da assinatura | Crie uma nova assinatura com outro cartão registrado | | Cobrança com `cardTokenId` falha depois da exclusão | Token revogado | Registre o cartão de novo em [Registrar cartão](/referencia/cartoes/registrar) | | `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` | ```http REST (JSON) theme={null} DELETE /v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X DELETE "https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q', { method: 'DELETE', headers: { Authorization: `Basic ${credentials}` } }, ); const result = await response.json(); if (result.deleted) { // remova o cartão da tela "meus cartões" } ``` ```python Python theme={null} import os import requests response = requests.request( "DELETE", "https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'DELETE', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .method("DELETE", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Delete, "https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("DELETE", "https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/cards/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Delete.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "deleted": true, "message": "Card deleted successfully" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Card not found" } ``` ## Veja também > [card] [Cofre de cartões](/guias/cofre-de-cartoes) > > Ciclo de vida do cartão salvo. > [card] [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida) > > Cancelar e recriar assinatura para trocar o cartão. > [card] [Cobrança com cartão salvo](/guias/cobrancas/cartao-salvo) > > Uso do `cardTokenId` em recompras. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guardar um novo cartão. # Listar cartões Source: https://docs.fastpaybrasil.com/referencia/cartoes/listar GET /v1/cards Devolve os cartões salvos no cofre da sua conta, com filtro opcional por cliente. Esta rota devolve os cartões registrados no cofre da Finvia pela sua conta. Com o filtro `customerId`, você obtém os cartões de um cliente específico, o que permite montar a tela "meus cartões" no seu site ou mostrar ao cliente, no checkout, o cartão que ele já usou. É também a fonte confiável para saber se um cartão pode ser usado em [`POST /v1/charges`](/referencia/cobrancas/criar): a cobrança recusa cartão `revoked` ou `expired`, e o `status` desta listagem mostra exatamente essa situação. ## Quando usar | Situação | Como usar esta rota | | - | - | | Checkout de recompra: mostrar os cartões salvos do cliente | `customerId` com o `id` do cliente | | Tela "meus cartões" na área logada | `customerId` e exiba `maskedNumber`, `brand` e validade | | Conferir se um cartão está pronto para cobrança | Verifique se `status` é `active` (prefira esta rota a [Consultar cartão](/referencia/cartoes/consultar) para essa decisão) | | Ver os detalhes de um cartão cujo `id` você já tem | Use [Consultar cartão](/referencia/cartoes/consultar) | ## Antes de chamar * Tenha uma chave secreta (`sk_`) válida ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * A rota devolve os cartões da conta dona da chave. Cartões registrados por outra conta ou subconta não aparecem. ## Parâmetros de consulta **customerId** `string` Filtra pelo ID do cliente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. Com este filtro, vêm só cartões não excluídos (`active` ou `expired`). Sem ele, os cartões excluídos (`revoked`) também aparecem. > [!NOTE] > > Esta listagem **não é paginada**: a resposta é um array de cartões, sem `page`, `size` nem envelope. Ela traz no máximo os **20 cartões mais recentes** da conta. Para encontrar o cartão de um cliente específico, use sempre o filtro `customerId`. ## Respostas A resposta `200` é um **array**. Cada item tem os campos abaixo. **id** `string` ID do token do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. É o valor usado como `cardTokenId` em cobranças e assinaturas. **token** `string` Token do cartão. Ex.: `tok_abc123xyz`. **maskedNumber** `string | null` Número mascarado do cartão. Ex.: `****1111`. **brand** `string` Bandeira do cartão. Ex.: `visa`. **expirationMonth** `string` Mês de validade. Ex.: `12`. **expirationYear** `string` Ano de validade. Ex.: `2028`. **status** `string` Situação do cartão no cofre: `active`, `expired` ou `revoked`. Os valores `pending_validation` e `inactive` nunca aparecem nesta listagem. **createdAt** `string` Data e hora de criação (formato `date-time`). Ex.: `2024-01-15T10:30:00.000Z`. | `status` | O que significa | Pode ser cobrado? | | - | - | - | | `active` | Cartão pronto para uso | Sim | | `expired` | A validade do cartão passou | Não | | `revoked` | Cartão excluído com [`DELETE /v1/cards/{id}`](/referencia/cartoes/excluir) | Não | | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista devolvida | Array de cartões | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | > [!NOTE] > > **Para o negócio:** mostrar ao cliente o cartão salvo ("Visa final 1111, validade 12/2028") permite oferecer recompra sem digitar o número do cartão de novo. Na cobrança, o cliente ainda informa o CVV. Só cartões com `status` `active` podem ser usados. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Lista vazia para um cliente que tem cartão | O cartão foi registrado com a chave de outra conta ou subconta | Use a chave da conta que registrou o cartão | | Cartão antigo não aparece sem filtro | A listagem traz só os 20 cartões mais recentes da conta | Filtre por `customerId` | | Cartão aparece na lista, mas a cobrança falha | `status` `expired` ou `revoked` | Use só cartões `active` e peça outro cartão ao cliente nos demais casos | | Código quebra ao ler `meta` ou `data` | A resposta é um array direto | Itere sobre a resposta, sem esperar envelope de paginação | | `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` | ```http REST (JSON) theme={null} GET /v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q', { headers: { Authorization: `Basic ${credentials}` } }, ); const cards = await response.json(); // array const usaveis = cards.filter((card) => card.status === 'active'); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} [ { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "token": "tok_abc123xyz", "maskedNumber": "****1111", "brand": "visa", "expirationMonth": "12", "expirationYear": "2028", "status": "active", "createdAt": "2024-01-15T10:30:00.000Z" } ] ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## Veja também > [card] [Cofre de cartões](/guias/cofre-de-cartoes) > > Como os cartões ficam guardados e quando podem ser usados. > [card] [Cobrança com cartão salvo](/guias/cobrancas/cartao-salvo) > > Usar o cartão listado em uma recompra. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guardar um novo cartão no cofre. > [card] [Guia de clientes](/guias/clientes) > > O cliente dono do cartão. # Registrar um cartão Source: https://docs.fastpaybrasil.com/referencia/cartoes/registrar POST /v1/cards Guarda o cartão de crédito de um cliente no cofre da Finvia para recompra com um clique e assinaturas. Esta rota guarda o cartão de crédito de um cliente no cofre de cartões da Finvia (tokenização: o número do cartão fica com a Finvia e você recebe um identificador para usar no lugar dele). O `id` devolvido é o que você envia depois como `cardTokenId` na [cobrança com cartão salvo](/guias/cobrancas/cartao-salvo) e na [assinatura](/referencia/assinaturas/criar). O seu sistema não precisa guardar o número do cartão. O cartão já nasce `active`: não há transação de teste, valor para conferir na fatura nem etapa de ativação. O registro também não cobra nada do cliente. ## Quando usar | Situação | Como usar esta rota | | - | - | | Assinatura no fluxo recomendado (cards-first) | Crie o cliente, registre o cartão aqui e crie a assinatura com `cardTokenId` | | Recompra com um clique | Registre o cartão na primeira compra; nas seguintes, cobre com `cardTokenId` e o CVV | | Cliente quer trocar o cartão de uma assinatura | Registre o novo cartão, cancele a assinatura e crie outra com o novo `cardTokenId` (não existe troca de cartão na assinatura) | | Venda avulsa sem intenção de reaproveitar o cartão | Não é preciso registrar. Cobre direto em [Criar cobrança](/referencia/cobrancas/criar) com os dados do cartão | ## Antes de chamar * Tenha uma chave secreta (`sk_`) válida ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Tenha o `id` de um cliente com **e-mail** e **CPF ou CNPJ** ([Criar cliente](/referencia/clientes/criar)). O tipo do documento é deduzido pela quantidade de dígitos de `document.id`: 11 dígitos é CPF e 14 é CNPJ. Qualquer outro tamanho (passaporte, RG) conta como cliente sem documento, e o registro é recusado. * O cartão fica vinculado à conta dona da chave que o registrou. Ele não pode ser usado por outro merchant nem por outra subconta. > [!WARNING] > > O cadastro de cartão não tem modo de teste. Mesmo com a chave de teste (`sk_test_`), o cartão é registrado de verdade na adquirente, sem nenhuma cobrança. O cofre é o mesmo para teste e produção: um `cardTokenId` criado na homologação também funciona com a chave de produção, e aí a cobrança é real. Veja como homologar em [Cofre de cartões](/guias/cofre-de-cartoes). > [!WARNING] > > Cartão salvo **não** permite cobrar sem o cliente presente em [`POST /v1/charges`](/referencia/cobrancas/criar): o CVV do comprador é obrigatório em toda cobrança com `cardTokenId`. Sem ele, a resposta é `400` com `CVV is required when using cardTokenId`. Para cobrança automática a cada ciclo, use [Assinaturas](/guias/assinaturas/visao-geral). ## Corpo da requisição Campos obrigatórios: `customerId`, `number`, `holderName`, `expirationMonth`, `expirationYear` e `cvv`. **customerId** `string` *required* ID do cliente dono do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. O cliente precisa ter e-mail e CPF ou CNPJ. **number** `string` *required* Número do cartão. Ex.: `4111111111111111`. **holderName** `string` *required* Nome impresso no cartão. Ex.: `JOAO SILVA`. **expirationMonth** `string` *required* Mês de validade, de `01` a `12`, com 2 caracteres (`minLength` 2, `maxLength` 2). Ex.: `12`. **expirationYear** `string` *required* Ano de validade no formato `YYYY`, com 4 caracteres (`minLength` 4, `maxLength` 4). Ex.: `2028`. **cvv** `string` *required* Código de segurança. Mínimo de 3 caracteres. Ex.: `123`. **alias** `string` Apelido opcional para o cartão. Ex.: `Cartão pessoal`. **validateCard** `boolean` *deprecated* Obsoleto. O campo é aceito, mas não tem efeito: o cartão sempre nasce `active`, sem transação de teste. Não é preciso enviá-lo. ## Respostas **id** `string` ID do token do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. É o valor usado como `cardTokenId` em cobranças e assinaturas e como `id` nas rotas de cartão. **token** `string` Token do cartão para referência futura. Ex.: `tok_abc123xyz`. **maskedNumber** `string | null` Número mascarado do cartão (4 últimos dígitos). Ex.: `****1111`. Use para mostrar o cartão ao cliente ("cartão final 1111"). **status** `string` Situação do cartão. Vem sempre `active`. **pendingActivation** `boolean` Vem sempre `false`. O campo continua na resposta por compatibilidade. | HTTP | Significado | Corpo | | - | - | - | | `201` | Cartão registrado | `id`, `token`, `maskedNumber`, `status`, `pendingActivation` | | `400` | Cliente sem e-mail ou sem CPF/CNPJ | `{"statusCode": 400, "message": "Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador"}` | | `400` | Dados do cartão inválidos ou outra falha no registro | `{"statusCode": 400, "message": "Failed to register card"}` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | > [!NOTE] > > **Para o negócio:** com o cartão no cofre, o cliente não precisa digitar o número de novo nas próximas compras: em cada recompra, ele informa só o CVV. Em assinaturas, o cartão registrado é cobrado automaticamente a cada ciclo. O cartão fica disponível apenas para a conta que o registrou. > [!TIP] > > **Para o desenvolvedor:** guarde no seu sistema o `id`, o `maskedNumber` e, se quiser, o `alias`. Nunca guarde `number` nem `cvv`. Em evidências de homologação, envie a requisição sem o número completo do cartão. Para saber depois se o cartão ainda pode ser cobrado, use [Listar cartões](/referencia/cartoes/listar). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` com `O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 nem 14 dígitos (passaporte, RG) | Use um cliente com e-mail e CPF ou CNPJ. O documento não pode ser alterado depois da criação: veja o [guia de clientes](/guias/clientes) | | `400` com `Failed to register card` | Dados do cartão inválidos (validade com tamanho errado, CVV curto) | Envie `expirationMonth` com 2 caracteres, `expirationYear` com 4 e `cvv` com pelo menos 3 | | Cartão registrado não funciona em outra conta ou subconta | O cartão pertence à conta que o registrou | Registre o cartão com a chave da conta que vai cobrar | | `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` | ## Como testar O cenário **SUB-01** da [homologação](/homologacao/roteiro) pede o registro de um cartão para um cliente com e-mail e CPF ou CNPJ, com resultado `status: "active"` e `pendingActivation: false`. Na sequência, o **SUB-02** usa o cartão registrado em uma cobrança com `cardTokenId` e `cvv`. Como o cadastro não tem modo de teste, use um cartão real. Com a chave de teste, a cobrança do SUB-02 é simulada e não movimenta dinheiro. ```http REST (JSON) theme={null} POST /v1/cards HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/cards" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/cards', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ customerId: '2RhQg9M7ZCg3X3nMb9W1kX8Q', number: cardNumber, // vindo do formulário, nunca gravado no seu banco holderName: 'MARIA SOUZA', expirationMonth: '10', expirationYear: '2028', cvv, alias: 'Cartão pessoal', }), }); const card = await response.json(); if (!response.ok) { throw new Error(`Falha ao registrar o cartão: ${response.status}`); } // card.id é o cardTokenId usado em cobranças e assinaturas ``` ```python Python theme={null} import os import requests payload = { "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/cards", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2RhQg9M7ZCg3X3nMb9W1kX8Q', 'number' => '4111111111111111', 'holderName' => 'JOAO SILVA', 'expirationMonth' => '12', 'expirationYear' => '2028', 'cvv' => '123', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/cards'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/cards")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/cards"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number": "4111111111111111", "holderName": "JOAO SILVA", "expirationMonth": "12", "expirationYear": "2028", "cvv": "123" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/cards", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/cards") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "customerId" => "2RhQg9M7ZCg3X3nMb9W1kX8Q", "number" => "4111111111111111", "holderName" => "JOAO SILVA", "expirationMonth" => "12", "expirationYear" => "2028", "cvv" => "123", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "token": "tok_abc123xyz", "maskedNumber": "****1111", "status": "active", "pendingActivation": false } ``` ```json 400 Cliente sem CPF/CNPJ theme={null} { "statusCode": 400, "message": "Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador" } ``` ```json 400 theme={null} { "statusCode": 400, "message": "Failed to register card" } ``` ## Veja também > [card] [Cofre de cartões](/guias/cofre-de-cartoes) > > Como funciona o armazenamento e o ciclo de vida do cartão. > [card] [Cobrança com cartão salvo](/guias/cobrancas/cartao-salvo) > > Recompra com `cardTokenId` e CVV. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo cards-first: cliente, cartão e assinatura. > [card] [Guia de clientes](/guias/clientes) > > Requisitos do cliente para ter cartão salvo. # Atualizar um cliente Source: https://docs.fastpaybrasil.com/referencia/clientes/atualizar PUT /v1/customers/{id} Altera nome, e-mail ou telefone de um cliente. O documento não pode ser alterado depois da criação. Esta rota mantém o cadastro do cliente em dia: quando o comprador troca de e-mail, corrige o nome ou muda de telefone no seu sistema, você reflete a mudança aqui. ## Quando usar | Situação | Como usar esta rota | | - | - | | Cliente alterou o e-mail no perfil do seu site | Envie só `email` | | Correção de nome digitado errado | Envie só `name` | | Novo número de telefone | Envie só `phoneNumber` | | CPF ou CNPJ cadastrado errado | Esta rota não altera documento. Crie um novo cliente com [Criar cliente](/referencia/clientes/criar) | ## Antes de chamar * Tenha uma chave secreta (`sk_`) válida, do mesmo ambiente em que o cliente foi criado ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Tenha o `id` do cliente. > [!WARNING] > > `documentId` e `documentType` **não podem ser alterados** depois da criação. O corpo desta rota aceita apenas `name`, `email` e `phoneNumber`. ## Parâmetros de caminho **id** `string` *required* Identificador único do cliente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Corpo da requisição O corpo é obrigatório, mas nenhum campo dele é obrigatório: envie apenas os que vão mudar. **name** `string` Nome completo do cliente. Ex.: `Joao da Silva`. **email** `string` E-mail do cliente (formato `email`). Ex.: `joao.silva@email.com`. **phoneNumber** `string` Telefone do cliente. Ex.: `+5511987654321`. > [!TIP] > > **Para o desenvolvedor:** o contrato não marca nenhum campo como obrigatório no corpo. Para evitar sobrescrever dados por engano, envie só os campos que o usuário de fato alterou e trate qualquer `200` como alteração aplicada. ## Respostas A resposta `200` traz o cadastro do cliente, no mesmo formato de [Consultar cliente](/referencia/clientes/consultar). Os campos desse cadastro ainda não estão publicados: o time técnico vai definir o formato final. | HTTP | Significado | Corpo | | - | - | - | | `200` | Cliente atualizado | Cadastro do cliente | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `404` | Cliente não encontrado | `{"statusCode": 404, "message": "Customer not found"}` | > [!NOTE] > > **Para o negócio:** como o documento fica fixo, um erro de CPF ou CNPJ no cadastro só se resolve com um cliente novo. Vale validar o documento no seu formulário antes de criar o cliente. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` com `Customer not found` | `id` incorreto, cliente excluído ou criado no outro ambiente | Confira o `id` e a chave usada | | Documento continua igual depois da chamada | `documentId` e `documentType` não são alteráveis | Crie um novo cliente com o documento correto | | `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` | ```http REST (JSON) theme={null} PUT /v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "name": "Joao da Silva", "email": "joao.silva@email.com", "phoneNumber": "+5511987654321" } ``` ```bash cURL theme={null} curl -X PUT "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "name": "Joao da Silva", "email": "joao.silva@email.com", "phoneNumber": "+5511987654321" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q', { method: 'PUT', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ email: 'joao.silva@email.com' }), }, ); if (!response.ok) { const erro = await response.json(); // 401 ou 404 } ``` ```python Python theme={null} import os import requests payload = { "name": "Joao da Silva", "email": "joao.silva@email.com", "phoneNumber": "+5511987654321", } response = requests.request( "PUT", "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'Joao da Silva', 'email' => 'joao.silva@email.com', 'phoneNumber' => '+5511987654321', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'PUT', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "name": "Joao da Silva", "email": "joao.silva@email.com", "phoneNumber": "+5511987654321" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("PUT", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "name": "Joao da Silva", "email": "joao.silva@email.com", "phoneNumber": "+5511987654321" } """; var request = new HttpRequestMessage(HttpMethod.Put, "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "name": "Joao da Silva", "email": "joao.silva@email.com", "phoneNumber": "+5511987654321" }`) req, err := http.NewRequest("PUT", "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Put.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "name" => "Joao da Silva", "email" => "joao.silva@email.com", "phoneNumber" => "+5511987654321", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 404 theme={null} { "statusCode": 404, "message": "Customer not found" } ``` ## Veja também > [card] [Guia de clientes](/guias/clientes) > > Boas práticas de cadastro. > [card] [Consultar cliente](/referencia/clientes/consultar) > > Conferir o cadastro depois da alteração. > [card] [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida) > > O que muda e o que não muda em uma assinatura ativa. > [card] [Cofre de cartões](/guias/cofre-de-cartoes) > > Cartões vinculados ao cliente. # Consultar um cliente Source: https://docs.fastpaybrasil.com/referencia/clientes/consultar GET /v1/customers/{id} Devolve o cadastro completo de um cliente a partir do identificador dele. Esta rota devolve o cadastro de um cliente. Use quando você já tem o `id` (guardado no seu sistema, recebido em [Criar cliente](/referencia/clientes/criar) ou em [Listar clientes](/referencia/clientes/listar)) e precisa conferir o cadastro antes de uma operação. ## Quando usar | Situação | Como usar esta rota | | - | - | | Conferir se o cliente tem e-mail e CPF ou CNPJ antes de registrar um cartão | Consulte pelo `id` e confira o e-mail e o documento do cadastro | | Mostrar os dados do comprador na tela de atendimento | Consulte pelo `id` guardado no pedido | | Verificar se uma atualização foi aplicada | Consulte o cliente depois de [Atualizar cliente](/referencia/clientes/atualizar) | | Encontrar um cliente pelo e-mail ou documento | Use [Listar clientes](/referencia/clientes/listar) com filtro | ## Antes de chamar * Tenha uma chave secreta (`sk_`) válida, do mesmo ambiente (teste ou produção) em que o cliente foi criado ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Tenha o `id` do cliente. ## Parâmetros de caminho **id** `string` *required* Identificador único do cliente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Respostas A resposta `200` traz o cadastro do cliente. **Em validação (V-37):** os campos do cliente na resposta e o exemplo estão retidos até o time técnico definir o formato final. Os nomes dos campos vão mudar em relação à versão atual. | HTTP | Significado | Corpo | | - | - | - | | `200` | Cliente encontrado | Cadastro do cliente | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `404` | Cliente não encontrado | `{"statusCode": 404, "message": "Customer not found"}` | > [!TIP] > > **Para o desenvolvedor:** para salvar um cartão, o cliente precisa ter e-mail e CPF (11 dígitos) ou CNPJ (14 dígitos). Sem isso, [Registrar cartão](/referencia/cartoes/registrar) responde `400`. Enquanto os campos desta resposta não são publicados, garanta esses dados no momento em que cria o cliente. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` com `Customer not found` | `id` incorreto, cliente excluído ou criado no outro ambiente | Confira o `id` e use a chave do ambiente em que o cliente foi criado | | `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` | ```http REST (JSON) theme={null} GET /v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q', { headers: { Authorization: `Basic ${credentials}` } }, ); if (response.status === 404) { // cliente não existe neste ambiente } const customer = await response.json(); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 404 theme={null} { "statusCode": 404, "message": "Customer not found" } ``` ## Veja também > [card] [Guia de clientes](/guias/clientes) > > Ciclo de vida do cadastro do cliente. > [card] [Atualizar cliente](/referencia/clientes/atualizar) > > Mudar nome, e-mail ou telefone. > [card] [Listar cartões](/referencia/cartoes/listar) > > Cartões salvos do cliente, filtrando por `customerId`. > [card] [Cartão salvo](/guias/cobrancas/cartao-salvo) > > Recompra com o cartão guardado no cofre. # Criar um cliente Source: https://docs.fastpaybrasil.com/referencia/clientes/criar POST /v1/customers Cadastra o comprador com nome, e-mail e documento para usar depois em cobranças, cartões salvos e assinaturas. Esta rota cadastra um cliente (objeto `customer`), a pessoa ou empresa que paga. O cadastro devolve um `id` que você guarda no seu sistema e reutiliza: para registrar o cartão no cofre, para criar uma assinatura ou para cobrar sem reenviar os dados pessoais a cada venda. ## Quando usar | Situação | Como usar esta rota | | - | - | | Fluxo de assinatura com cartão registrado antes (cards-first) | Crie o cliente, depois [registre o cartão](/referencia/cartoes/registrar) com o `id` devolvido | | Cadastro feito no seu site antes da primeira compra | Crie o cliente no momento do cadastro e guarde o `id` junto do usuário | | Recompra com um clique | Cliente criado aqui + cartão salvo + [cobrança com `cardTokenId`](/guias/cobrancas/cartao-salvo) | | Venda avulsa sem cadastro prévio | Não é preciso chamar esta rota: [Criar cobrança](/referencia/cobrancas/criar) aceita `name` e `email` e cria ou localiza o cliente | ## Antes de chamar * Tenha uma chave secreta (`sk_`) válida. A chave herda as permissões do usuário que a gerou, e esta rota devolve `403` quando a chave não tem permissão ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Confira se o cliente já existe com [Listar clientes](/referencia/clientes/listar) filtrando por `email` ou `documentId`, para não duplicar o cadastro. * Se o cliente vai ter cartão salvo ou assinatura, colete **e-mail** e **CPF ou CNPJ**. Sem esses dois dados, o cartão não pode ser salvo. > [!WARNING] > > O documento **não pode ser alterado depois**: [Atualizar cliente](/referencia/clientes/atualizar) muda só nome, e-mail e telefone. Para registrar cartão (em `POST /v1/cards` ou no cartão enviado direto em `POST /v1/subscriptions`), o cliente precisa ter e-mail e CPF ou CNPJ. O tipo é deduzido pela quantidade de dígitos de `documentId`: 11 dígitos é CPF e 14 é CNPJ. Qualquer outro documento (passaporte, RG) conta como cliente sem documento, e o cartão é recusado com `400`. ## Corpo da requisição Campos obrigatórios: `name`, `email`, `documentId` e `documentType`. **name** `string` *required* Nome completo do cliente. Ex.: `Joao Silva`. **email** `string` *required* E-mail do cliente (formato `email`). Ex.: `joao@email.com`. **documentId** `string` *required* Número do documento de identificação. Ex.: `52998224725` (CPF, 11 dígitos) ou `11222333000181` (CNPJ, 14 dígitos). **documentType** `string` *required* Tipo do documento. Use `cpf` ou `cnpj`. Para salvar cartão, o que conta é a quantidade de dígitos de `documentId`, e não o valor deste campo. **phoneNumber** `string` Telefone do cliente (opcional). Ex.: `+5511987654321`. > [!TIP] > > **Para o desenvolvedor:** envie o `documentId` como string, sem pontos, barras ou traços, como nos exemplos (`52998224725`). Guarde o `id` da resposta na tabela de usuários do seu sistema: ele é a chave para todas as operações seguintes com esse cliente. ## Respostas **id** `string` Identificador único do cliente criado. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. Use em `customerId` ao [registrar um cartão](/referencia/cartoes/registrar) ou criar uma [assinatura](/referencia/assinaturas/criar), e em `customer.id` ao [criar uma cobrança](/referencia/cobrancas/criar). A resposta traz só o `id`. Para ver o cadastro completo, use [Consultar cliente](/referencia/clientes/consultar). | HTTP | Significado | Corpo | | - | - | - | | `201` | Cliente criado | `{"id": "..."}` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Sem permissão | `{ "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 }` | > [!NOTE] > > **Para o negócio:** ter o cliente cadastrado com CPF ou CNPJ e e-mail é a condição para oferecer recompra com cartão salvo e cobrança recorrente. Se o seu produto tem assinatura, peça esses dados já no cadastro do site ou do aplicativo, assim o cliente não precisa preencher nada a mais no momento da contratação. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` | | `403 Forbidden` | A chave herda as permissões do usuário que a gerou, e esse usuário não tem acesso à rota | Gere a chave com um usuário que tenha a permissão (para integração, use Owner ou Manager) | | Registro de cartão recusado para o cliente | Cliente sem e-mail ou com documento que não tem 11 nem 14 dígitos | Cadastre o cliente com e-mail e CPF ou CNPJ | | Documento cadastrado errado | O documento não muda depois da criação | Crie um novo cliente com o documento correto | | Mesmo cliente cadastrado mais de uma vez | Criação sem verificar se já existia | Antes de criar, consulte [Listar clientes](/referencia/clientes/listar) com `email` ou `documentId` | ```http REST (JSON) theme={null} POST /v1/customers HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/customers', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Maria Souza', email: 'maria@email.com', documentId: '11222333000181', documentType: 'cnpj', }), }); const { id } = await response.json(); ``` ```python Python theme={null} import os import requests payload = { "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/customers", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'Joao Silva', 'email' => 'joao@email.com', 'documentId' => '52998224725', 'documentType' => 'cpf', 'phoneNumber' => '+5511987654321', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/customers'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/customers"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "name": "Joao Silva", "email": "joao@email.com", "documentId": "52998224725", "documentType": "cpf", "phoneNumber": "+5511987654321" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/customers", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/customers") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "name" => "Joao Silva", "email" => "joao@email.com", "documentId" => "52998224725", "documentType" => "cpf", "phoneNumber" => "+5511987654321", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 403 theme={null} { "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 } ``` ## Veja também > [card] [Guia de clientes](/guias/clientes) > > Quando cadastrar e como reaproveitar o cliente. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Próximo passo do fluxo cards-first. > [card] [Cofre de cartões](/guias/cofre-de-cartoes) > > Como os cartões ficam guardados e são reutilizados. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Cliente, plano e cartão na cobrança recorrente. # Excluir um cliente Source: https://docs.fastpaybrasil.com/referencia/clientes/excluir DELETE /v1/customers/{id} Remove um cliente do sistema por exclusão lógica (soft delete). Esta rota remove um cliente da sua base. O contrato da API classifica a operação como exclusão lógica (soft delete). Use quando o cliente pede para encerrar o cadastro ou quando você precisa limpar registros duplicados. ## Quando usar | Situação | Como usar esta rota | | - | - | | Cliente pediu o encerramento do cadastro no seu serviço | Exclua pelo `id` | | Limpeza de cadastros duplicados | Escolha o cadastro que fica e exclua os demais | | Cliente com documento cadastrado errado | Crie o cadastro correto com [Criar cliente](/referencia/clientes/criar) e exclua o antigo | | Remover só o cartão salvo, mantendo o cliente | Use [Excluir cartão](/referencia/cartoes/excluir) | ## Antes de chamar * Tenha uma chave secreta (`sk_`) válida, do mesmo ambiente em que o cliente foi criado ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Tenha o `id` do cliente. * Se o cliente tem assinaturas ativas ou cartões salvos, decida antes o que fazer com eles: cancele as assinaturas em [Cancelar assinatura](/referencia/assinaturas/cancelar) e remova os cartões em [Excluir cartão](/referencia/cartoes/excluir), se for o caso. > [!NOTE] > > A documentação da API não descreve o que acontece com cartões salvos, assinaturas e cobranças de um cliente excluído. Trate esses vínculos de forma explícita, com as rotas próprias de cada recurso, antes de excluir o cliente. ## Parâmetros de caminho **id** `string` *required* Identificador único do cliente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. Esta rota não tem corpo de requisição nem parâmetros de consulta. ## Respostas A resposta de sucesso é `204` **sem corpo**. | HTTP | Significado | Corpo | | - | - | - | | `204` | Cliente excluído | Sem corpo | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `404` | Cliente não encontrado | `{"statusCode": 404, "message": "Customer not found"}` | > [!TIP] > > **Para o desenvolvedor:** não tente ler JSON da resposta `204`, o corpo vem vazio. Em Node.js, verifique `response.status === 204` (ou `response.ok`) antes de qualquer `response.json()`. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Erro ao interpretar a resposta como JSON | A resposta `204` não tem corpo | Verifique o status e não chame `json()` | | `404` com `Customer not found` | `id` incorreto, cliente já excluído ou criado no outro ambiente | Confira o `id` e a chave usada | | `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` | ```http REST (JSON) theme={null} DELETE /v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X DELETE "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q', { method: 'DELETE', headers: { Authorization: `Basic ${credentials}` } }, ); if (response.status === 204) { // cliente excluído } else { const erro = await response.json(); // 401 ou 404 } ``` ```python Python theme={null} import os import requests response = requests.request( "DELETE", "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'DELETE', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .method("DELETE", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Delete, "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("DELETE", "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Delete.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 204 theme={null} (sem corpo) ``` ```json 404 theme={null} { "statusCode": 404, "message": "Customer not found" } ``` ## Veja também > [card] [Guia de clientes](/guias/clientes) > > Criação, manutenção e remoção de clientes. > [card] [Excluir cartão](/referencia/cartoes/excluir) > > Revogar um cartão salvo no cofre. > [card] [Ciclo de vida da assinatura](/guias/assinaturas/ciclo-de-vida) > > Cancelamento e estorno de assinaturas. > [card] [Listar clientes](/referencia/clientes/listar) > > Encontrar cadastros duplicados. # Listar clientes Source: https://docs.fastpaybrasil.com/referencia/clientes/listar GET /v1/customers Busca os clientes cadastrados na sua conta, com filtro por nome, e-mail, documento ou telefone e paginação. Esta rota devolve, página a página, os clientes (objeto `customer`) cadastrados na sua conta. Use para montar uma tela de clientes no seu sistema, para encontrar o `id` de um cliente antes de cobrar ou registrar um cartão e para conferir se uma pessoa já tem cadastro antes de criar outro. ## Quando usar | Situação | Como usar esta rota | | - | - | | Tela de busca de clientes no seu painel | `search` com o termo digitado pelo operador | | Descobrir se um e-mail já tem cadastro antes de criar o cliente | `email` com o endereço exato | | Localizar o cliente pelo CPF ou CNPJ | `documentId` com o número do documento | | Exportar ou sincronizar a base de clientes | Percorra as páginas com `page` e `size` até o valor de `pages` | | Ver os dados de um cliente cujo `id` você já tem | Use [Consultar cliente](/referencia/clientes/consultar) | ## Antes de chamar * Tenha uma chave secreta (`sk_`) válida ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * A rota lista os clientes da conta dona da chave. Com a chave de teste, você vê os clientes do ambiente de testes. ## Parâmetros de consulta Todos os parâmetros são opcionais. Sem nenhum filtro, a rota devolve a primeira página com até 10 clientes, dos mais recentes para os mais antigos. **search** `string` Busca por nome, e-mail, documento ou telefone. Ex.: `joao`. **email** `string` Filtra pelo e-mail **exato**. Ex.: `joao@email.com`. **documentId** `string` Filtra pelo número do documento. Ex.: `52998224725`. **page** `integer` (default: 1) Número da página. Começa em `1`. Valor menor que 1 ou não numérico volta ao padrão. **size** `integer` (default: 10) Quantidade de itens por página. Valor menor que 1 ou não numérico volta ao padrão. > [!WARNING] > > O tamanho da página vai em `size`. Um parâmetro `limit` é ignorado sem erro: `limit=50` continua devolvendo 10 itens. > [!TIP] > > **Para o desenvolvedor:** `search` serve para busca livre (uma caixa de pesquisa, por exemplo). Para checar se um cliente já existe antes de criar outro, prefira `email` ou `documentId`, que são filtros diretos. As regras gerais de paginação estão em [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia). ## Respostas A resposta usa o mesmo envelope plano das outras listagens paginadas da API. **data** `object[]` Clientes da página atual. **total** `integer` Total de clientes encontrados com os filtros enviados. **page** `integer` Página atual. **size** `integer` Itens por página. **pages** `integer` Total de páginas. **Em validação (V-37):** os campos de cada cliente em `data` e o exemplo de resposta estão retidos até a correção desta listagem pelo time técnico. | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista devolvida | `data`, `total`, `page`, `size` e `pages` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | > [!NOTE] > > **Para o negócio:** um cliente pode nascer de duas formas: pelo cadastro direto em [Criar cliente](/referencia/clientes/criar) ou automaticamente, quando uma cobrança ou assinatura recebe nome e e-mail sem um `id`. Esta rota é a forma de a equipe encontrar um cadastro e recuperar o identificador dele para as operações seguintes, como registrar um cartão. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401 Unauthorized` | Chave ausente, inválida ou codificada errado no Basic | Codifique em Base64 a chave seguida de `:` e envie no cabeçalho `Authorization` | | Lista vazia com chave de teste | Os clientes foram criados com a chave de produção (ou o contrário) | Use a chave do mesmo ambiente em que o cliente foi criado | | A página sempre volta com 10 itens | Parâmetro de tamanho enviado como `limit` | Envie `size` | | Filtro por e-mail não encontra o cliente | `email` faz comparação exata | Confira o endereço completo ou use `search` para busca livre | ```http REST (JSON) theme={null} GET /v1/customers?search=joao&page=1&size=10 HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const params = new URLSearchParams({ email: 'joao@email.com', page: '1', size: '10' }); const response = await fetch(`https://api-global.fastpaybrasil.com/v1/customers?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); const { data, total, pages } = await response.json(); console.log(`${total} cliente(s) em ${pages} página(s)`); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## Veja também > [card] [Guia de clientes](/guias/clientes) > > Quando cadastrar clientes e como eles se ligam a cartões e assinaturas. > [card] [Criar cliente](/referencia/clientes/criar) > > Cadastro com nome, e-mail e documento. > [card] [Consultar cliente](/referencia/clientes/consultar) > > Dados de um cliente pelo `id`. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > O cliente como primeiro passo da cobrança recorrente. # Consultar uma cobrança Source: https://docs.fastpaybrasil.com/referencia/cobrancas/consultar GET /v1/charges/{id} Devolve o estado atual de uma cobrança pelo ID: status, valores, cliente, forma de pagamento, bloqueio, split e dados de pré-chargeback. Esta rota devolve uma cobrança (charge) pelo seu identificador, com o status atual e todos os detalhes. Ela é a fonte de verdade para decidir o que fazer com um pedido: liberar o produto, cancelar, marcar como estornado ou como em disputa. É também a única rota que mostra a divisão do valor entre as contas (`splits`) e as tentativas agrupadas (`groupCharges`). ## Quando usar | Situação | Como usar esta rota | | - | - | | Recebeu um webhook ou postback | Consulte a cobrança pelo `id` do evento e confirme o `status` antes de liberar o pedido | | Antes de pedir um estorno | Confira se o `status` é `paid` | | Acompanhar uma disputa | Leia `isBlocked`: a liberação do bloqueio não gera webhook | | Conferir o split da venda | Leia a lista `splits` | | Tela de detalhe do pedido | Mostre forma de pagamento, parcelas, valor líquido e datas | | Mostrar de novo o QR Code Pix | Leia `paymentDetails.copyPaste` e `paymentDetails.qrCodeBase64` | | A criação deu timeout e você não tem o `id` | Esta rota não ajuda. Siga o [procedimento para timeout](/primeiros-passos/paginacao-ordenacao-idempotencia#idempotência) | | Ver várias cobranças de uma vez | Use [`GET /v1/charges`](/referencia/cobrancas/listar) | ## Antes de chamar * Tenha uma chave secreta do mesmo ambiente em que a cobrança foi criada: `sk_test_` para cobranças de teste e `sk_` para cobranças reais ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Tenha o `id` da cobrança, devolvido por [`POST /v1/charges`](/referencia/cobrancas/criar) e presente em todos os webhooks de cobrança (`data.id`). ## Parâmetros de caminho **id** `string` *required* Identificador único da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. ## Respostas A resposta `200` é o objeto de cobrança. Trate a ausência de qualquer campo. > [!WARNING] > > A API não usa `404` nesta rota: para um `id` que não existe, ela responde hoje **`200` com corpo vazio**. Trate corpo vazio como "cobrança não encontrada" e confira se a chave é do mesmo ambiente e da mesma conta da cobrança. **id** `string` Identificador único da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **status** `string` Status da cobrança: `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`, `pre_chargeback` ou `chargeback`. Ex.: `paid`. **isBlocked** `boolean` `true` enquanto a cobrança está bloqueada por uma disputa (MED no Pix ou chargeback no cartão). O `status` continua `paid` durante o bloqueio. Use este campo para saber se a cobrança está bloqueada. **blockedAt** `string | null` Data e hora do bloqueio, em ISO 8601. Continua preenchido depois da liberação, por isso não serve para saber se a cobrança ainda está bloqueada. **blockedReason** `string | null` Motivo do bloqueio, em texto livre preenchido pela equipe Finvia (pode indicar MED ou chargeback). Pode vir vazio e é apagado na liberação. **chargebackAlertRefunded** `boolean | null` Presente em cobranças com alerta de pré-chargeback (`status` `pre_chargeback`). `true`: o valor já foi estornado ao comprador como parte do tratamento do alerta. `false`: disputa aberta, sem estorno. `null` quando não há alerta. **chargebackAlertReason** `string | null` Motivo ou referência informado no alerta de pré-chargeback. Ex.: `Chargeback - NSU 123456789`. **pspRefId** `string | null` Identificador da cobrança no sistema do provedor de pagamento (PSP). Ex.: `ch_123456789`. **amount** `number` Valor total da cobrança, em reais. Ex.: `100.5`. **currency** `string` Moeda no padrão ISO 4217. Ex.: `BRL`. **spread** `number` Spread (taxa) aplicado à cobrança. Ex.: `2.5`. **net** `number` Valor líquido depois do spread. Ex.: `98`. **customer** `object` Cliente que pagou a cobrança. **propriedades** **id** `string` Identificador do cliente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **name** `string` Nome do cliente. Ex.: `Maria Souza`. **email** `string` E-mail do cliente. Ex.: `maria@email.com`. **document** `string` Documento do cliente, como texto. Ex.: `529.982.247-25`. **paymentMethod** `object` Forma de pagamento usada. Em cobranças Pix, traz `type` `pix`. Em cartão (digitado, salvo ou Apple Pay): **Cartão de crédito** **type** `string` *required* `credit_card`. **firstSix** `string` *required* Seis primeiros dígitos do cartão. Ex.: `444433`. **lastFour** `string` *required* Quatro últimos dígitos do cartão. Ex.: `1111`. **expirationMonth** `string` *required* Mês de validade. Ex.: `12`. **expirationYear** `string` *required* Ano de validade. Ex.: `2030`. **holderName** `string` *required* Nome do titular. Ex.: `MARIA SOUZA`. **installments** `number` *required* Número de parcelas usado. Ex.: `3`. **merchantId** `string` Identificador da conta dona da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **paymentDetails** `object | null` Detalhes do pagamento. O formato muda conforme a forma de pagamento. **Cartão de crédito** **firstSix** `string` *required* Seis primeiros dígitos do cartão. Ex.: `411111`. **lastFour** `string` *required* Quatro últimos dígitos do cartão. Ex.: `1111`. **expirationMonth** `string` *required* Mês de validade. Ex.: `12`. **expirationYear** `string` *required* Ano de validade. Ex.: `2030`. **holderName** `string` *required* Nome do titular. Ex.: `JOAO DA SILVA`. **installments** `number` *required* Número de parcelas usado. Ex.: `1`. **brand** `string` Bandeira do cartão. Opcional; aparece no Apple Pay. **Pix** **endToEndId** `string` Identificador End to End do Pix, preenchido quando o pagamento é confirmado. **copyPaste** `string` *required* Código Pix "copia e cola" (BR Code EMV). O pagador cola no app do banco para pagar. **qrCodeBase64** `string | null` Imagem do QR Code (PNG, 256x256) em data URI, gerada a partir do `copyPaste`. Pode ser usada direto no `src` de uma tag ``. Vem `null` ou ausente em cobranças criadas antes da introdução do campo ou quando o QR Code não pôde ser gerado; nesse caso, mostre o `copyPaste`. **expiresAt** `string` Data e hora de expiração do Pix, em ISO 8601. Opcional. **splits** `object[]` Divisão do valor entre as contas recebedoras. Aparece só nesta consulta (não vem na listagem nem na criação). Vem preenchida quando a cobrança teve `split` no POST ou quando a conta tem regra de split padrão para aquele método e moeda; nesse segundo caso, mesmo sem `split` na criação. **propriedades** **id** `string` ID do registro de split. **destinyMerchantId** `string` Conta recebedora. É o `merchantId` enviado em `split[]` na criação. **destinyMerchantName** `string` Nome fantasia da conta recebedora. **splitPercentage** `string` Percentual, como texto decimal. Ex.: `"30.00000000"`. Converta para número antes de calcular. **splitAmount** `number` Valor exibido para o recebedor, com 2 casas (truncado). O significado muda conforme o momento da cobrança: veja a tabela abaixo. **referenceAmount** `string` Base de cálculo: `net` (padrão, valor líquido depois da taxa transacional) ou `gross` (valor bruto, quando a conta está configurada assim). **groupCharges** `object[]` No cartão, tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas. A listagem mostra só a cobrança principal do grupo, e as demais tentativas aparecem aqui, na consulta da principal. **metadata** `object | null` Informações livres que você enviou na criação. Nesta resposta, as chaves voltam em **camelCase**: chaves enviadas em snake\_case chegam convertidas. Veja [Metadata](/guias/cobrancas/visao-geral#metadata). Ex.: `{"orderId": "ORD-123"}`. **paidAt** `string | null` Data e hora do pagamento, em ISO 8601. Ex.: `2026-10-15T14:30:00Z`. **createdAt** `string` Data e hora da criação, em ISO 8601. **updatedAt** `string` Data e hora da última atualização, em ISO 8601. ### O que `splitAmount` mostra Com base `net` (o padrão): | Momento da cobrança | O que `splitAmount` mostra | | - | - | | Parcelas a liquidar, sem antecipação concluída | Uma **simulação**: o valor que o recebedor teria se o originador antecipasse, já descontada a taxa de antecipação estimada. Não é o valor que será repassado | | Parcelas liquidadas sem antecipação | O repasse efetivo: percentual sobre o valor líquido, sem desconto de antecipação | | Depois de uma antecipação concluída | O valor efetivamente destinado, recalculado sobre o valor antecipado | Com base `gross`, mostra sempre percentual × valor bruto. O split pode aparecer também em cobrança recusada, mas o repasse só acontece quando a cobrança é paga. > [!TIP] > > **Para o desenvolvedor:** na conciliação do split, confira `destinyMerchantId` e `splitPercentage` e compare `splitAmount` com valor líquido × percentual. Enquanto a simulação de antecipação estiver ativa, o valor mostrado é menor que esse cálculo. | HTTP | Significado | Corpo | | - | - | - | | `200` | Cobrança encontrada, ou corpo vazio quando o `id` não existe | Objeto de cobrança ou vazio | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Perfil do usuário dono da chave sem permissão | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` | > [!NOTE] > > **Para o negócio:** use o `status` desta consulta como regra para liberar pedidos. `paid` libera; `pending` aguarda; `refused` e `failed` encerram a tentativa; `refunded` cancela o pedido. Uma cobrança `paid` com `isBlocked: true` está em disputa: o valor fica no saldo bloqueado até a decisão. Em `pre_chargeback`, olhe `chargebackAlertRefunded`: `true` significa que o valor já foi devolvido ao comprador. ## Como decidir pelo status | `status` | O que fazer no pedido | | - | - | | `pending` | Aguardar. No Pix, o cliente ainda não pagou o QR Code | | `paid` | Liberar o produto ou serviço. Se `isBlocked` for `true`, tratar como em disputa | | `refused` / `failed` | Não liberar. Oferecer nova tentativa ou outra forma de pagamento | | `in_analysis` | Aguardar a conclusão da análise antifraude | | `authentication_required` | A cobrança espera a autenticação do comprador. Veja [3DS gerenciado](/guias/3d-secure/gerenciado) | | `refunded` | Cancelar o pedido e, se for o caso, revogar o acesso | | `pre_chargeback` | Tratar conforme `chargebackAlertRefunded` | | `chargeback` | Chargeback formalizado. Veja [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) | ## Exemplos por caso de uso > [tab] Confirmar webhook > > Ao receber `charge.paid`, confirme o status antes de liberar o pedido. > > ```javascript theme={null} > app.post('/webhooks/finvia', async (req, res) => { > res.status(200).send('OK'); > > const { event, data } = req.body; > if (event !== 'charge.paid') return; > > const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); > const response = await fetch(`https://api-global.fastpaybrasil.com/v1/charges/${data.id}`, { > headers: { Authorization: `Basic ${credentials}` }, > }); > const texto = await response.text(); > if (!texto) return; // corpo vazio: cobrança não encontrada para esta chave > const charge = JSON.parse(texto); > > if (charge.status === 'paid' && !charge.isBlocked) { > await liberarPedido(charge.id); > } > }); > ``` > [tab] Acompanhar bloqueio > > A liberação do bloqueio não gera webhook. Consulte as cobranças que o seu sistema marcou como "em disputa". > > ```javascript theme={null} > const charge = await consultarCobranca(chargeId); > > if (charge.status === 'paid' && charge.isBlocked === false) { > // Bloqueio liberado: o valor voltou ao saldo disponível > } else if (charge.status === 'refunded' || charge.status === 'chargeback') { > // Disputa perdida: registre a perda > } > ``` > [tab] Reexibir o Pix > > O cliente fechou a página antes de pagar. Mostre o mesmo QR Code de novo. > > ```javascript theme={null} > const charge = await consultarCobranca(chargeId); > > if (charge.status === 'pending' && charge.paymentDetails) { > const { copyPaste, qrCodeBase64 } = charge.paymentDetails; > // Use qrCodeBase64 no src de uma imagem. Se vier null, gere o QR a partir de copyPaste. > } > ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `200` com corpo vazio para uma cobrança que existe | Chave de outro ambiente (teste x produção) ou de outra conta | Use a chave do mesmo ambiente e da mesma conta que criou a cobrança | | `200` com corpo vazio logo depois de criar | `id` copiado errado ou trocado por outro identificador, como o `pspRefId` | Use o campo `id` devolvido na criação | | `metadata.order_id` não encontrado | Nas respostas de `GET`, chaves enviadas em snake\_case vêm em camelCase | Leia `metadata.orderId` ou envie as chaves em camelCase. Veja [Metadata](/guias/cobrancas/visao-geral#metadata) | | Pedido continua "em disputa" para sempre | A liberação do bloqueio não gera webhook | Consulte a cobrança periodicamente e leia `isBlocked` | | `401` | Cabeçalho ausente ou Base64 sem os dois pontos no final | Decodifique o Base64 e confira se termina em `:` | | QR Code não aparece | `qrCodeBase64` veio `null` ou ausente | Gere a imagem a partir de `copyPaste` | ```http REST (JSON) theme={null} GET /v1/charges/2vorkDcXyvzifL63YX09S9VqcnI HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI', { headers: { Authorization: `Basic ${credentials}` }, }); const texto = await response.text(); const charge = texto ? JSON.parse(texto) : null; // null: cobrança não encontrada ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 Cartão com split theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "paid", "isBlocked": false, "blockedAt": null, "blockedReason": null, "chargebackAlertRefunded": null, "chargebackAlertReason": null, "pspRefId": "ch_123456789", "amount": 100, "currency": "BRL", "spread": 5, "net": 95, "customer": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Joao da Silva", "email": "joao@email.com", "document": "529.982.247-25" }, "paymentMethod": { "type": "credit_card", "firstSix": "411111", "lastFour": "1111", "expirationMonth": "12", "expirationYear": "2030", "holderName": "JOAO DA SILVA", "installments": 1 }, "merchantId": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH", "paymentDetails": { "firstSix": "411111", "lastFour": "1111", "expirationMonth": "12", "expirationYear": "2030", "holderName": "JOAO DA SILVA", "installments": 1 }, "splits": [ { "id": "2vorkSp1It2Re3Gi4St5Ro6AbCd", "destinyMerchantId": "2vorkRc9Ab8Cd7Ef6Gh5Ij4KlMn", "destinyMerchantName": "Loja Parceira", "splitPercentage": "30.00000000", "splitAmount": 28.5, "referenceAmount": "net" } ], "metadata": { "orderId": "ORD-123" }, "paidAt": "2026-10-15T14:30:00Z", "createdAt": "2026-10-15T14:30:00Z", "updatedAt": "2026-10-15T14:30:00Z" } ``` ```json 200 Pix bloqueado theme={null} { "id": "2vorkPx3Bl4Oc5Ke6Dd7Ab8CdEf", "status": "paid", "isBlocked": true, "blockedAt": "2026-10-20T09:00:00Z", "blockedReason": "MED em análise", "chargebackAlertRefunded": null, "chargebackAlertReason": null, "amount": 100, "currency": "BRL", "spread": 1, "net": 99, "paymentMethod": { "type": "pix" }, "merchantId": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH", "paymentDetails": { "endToEndId": "E12345678202610151430abcdef12345", "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD" }, "metadata": { "orderId": "ORD-456" }, "paidAt": "2026-10-15T14:31:00Z", "createdAt": "2026-10-15T14:30:00Z", "updatedAt": "2026-10-20T09:00:00Z" } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## Veja também > [card] [Listar cobranças](/referencia/cobrancas/listar) > > Várias cobranças com filtros por status, data e busca. > [card] [Estornar cobrança](/referencia/cobrancas/estornar) > > Estorno total de uma cobrança paga. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > O que significam `isBlocked` e o bloqueio de saldo. > [card] [Split](/guias/fast-connect/split) > > Prazos e regras do repasse. # Criar uma cobrança Source: https://docs.fastpaybrasil.com/referencia/cobrancas/criar POST /v1/charges Cria o pedido de pagamento que o seu cliente vai pagar: Pix, cartão de crédito, cartão salvo ou Apple Pay. Esta é a rota central da API. Nela você define **quanto** cobrar, **de quem**, **o que** está sendo vendido e **como** o cliente vai pagar. A mesma chamada atende venda avulsa em loja virtual, compra de curso, recompra com cartão salvo, Apple Pay e venda com divisão de valores entre contas (split). ## Quando usar | Situação | Como usar esta rota | | - | - | | Checkout de loja virtual | `paymentMethod.type` `pix` ou `credit_card`, com `shippingAddress` se algum item for físico | | Venda de produto digital | Itens com `type` `digital`, sem endereço de entrega | | Recompra com um clique | `credit_card` com `cardTokenId` e `cvv` | | Apple Pay | `credit_card` com o objeto `wallet` | | Marketplace | Qualquer forma de pagamento, com `split` | | Cobrança automática todo mês | Use [Assinaturas](/referencia/assinaturas/criar). Esta rota exige o CVV do comprador em toda cobrança com cartão | ## Antes de chamar * Tenha uma chave secreta gerada por usuário **Owner** ou **Manager** ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). Chave de usuário com perfil Desenvolvedor recebe `403`. * A sua conta precisa ter taxa configurada para o método e a moeda da cobrança. Sem ela, a API responde `422` `Fees not configured`, inclusive no Modo Teste. * Se algum item for `physical`, tenha o endereço de entrega. * Se vai usar split, as contas recebedoras precisam pertencer ao mesmo grupo [Connect](/guias/fast-connect/visao-geral). > [!WARNING] > > O valor vai em **reais**: `"amount": 10` significa R\$ 10,00. O mínimo é `1`. Enviar `1000` pensando em R\$ 10,00 gera uma cobrança de R\$ 1.000,00. > [!WARNING] > > A API não aceita cabeçalho de idempotência: cada chamada cria uma cobrança nova. Se a criação der timeout, **não reenvie de imediato**. Siga o [procedimento para timeout](/primeiros-passos/paginacao-ordenacao-idempotencia#idempotência): mande o número do seu pedido em `metadata`, recupere o `id` pelo webhook `charge.created` ou pela listagem e só crie outra cobrança se nada for encontrado. ## Corpo da requisição Campos obrigatórios: `amount`, `currency`, `customer`, `paymentMethod` e `items`. **amount** `number` *required* Valor da cobrança em reais (ex.: `10` = R\$ 10,00). Mínimo: `1`. **currency** `string` *required* Código da moeda no padrão ISO 4217. Ex.: `BRL`. Apple Pay e Pix aceitam só `BRL`. **customer** `object` *required* Quem está pagando. Há dois caminhos: informar o `id` de um cliente já cadastrado (os outros campos ficam opcionais e o cadastro existente é usado como está) ou enviar `name` + `email` (ou `phone`) para a API criar ou localizar o cliente na mesma chamada. **propriedades** **id** `string` ID de um cliente existente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **name** `string` Nome do cliente. Ex.: `Maria Souza`. **email** `string` E-mail do cliente. Obrigatório quando não há `id` nem `phone`. Ex.: `maria@email.com`. **phone** `string` Telefone do cliente. Pode substituir o `email` quando não há `id`. Ex.: `+5511987654321`. **document** `object` Documento do cliente. Obrigatório no Apple Pay. **propriedades** **type** `string` Tipo do documento: `cpf` ou `cnpj`. **id** `string` Número do documento. Ex.: `52998224725`. **address** `object` **propriedades** **country** `string` País no padrão ISO 3166-1 alpha-3. Ex.: `BRA`. **ipAddress** `string` IP do cliente no momento da compra. Ex.: `177.128.144.97`. **paymentMethod** `object` *required* Como o cliente vai pagar. Aceita quatro formatos, identificados pelo `type` e pelos campos que vêm junto. Veja [Formas de pagamento](#formas-de-pagamento) abaixo. **items** `object[]` *required* Lista do que está sendo vendido. Todos os campos do item são obrigatórios. **propriedades** **title** `string` *required* Nome do item. Ex.: `Tênis de corrida`. **type** `string` *required* Tipo do item: `physical` (entregue por correio ou transportadora) ou `digital`. Se algum item for `physical`, `shippingAddress` é obrigatório. **description** `string` *required* Descrição do item. Ex.: `Tamanho 38`. **unit\_price** `number` *required* Preço unitário, na mesma unidade de `amount` (reais, decimal). Ex.: `199.9`. **quantity** `number` *required* Quantidade. Ex.: `1`. **shippingAddress** `object` Endereço de entrega. Obrigatório quando algum item é `physical`. Sem ele, a API responde `400` antes de criar a cobrança: nenhum `id` é gerado e nenhum webhook é enviado. **propriedades** **postalCode** `string` *required* CEP. Ex.: `01310100`. **addressLine1** `string` *required* Logradouro e número. Ex.: `Av. Paulista, 1000`. **addressLine2** `string` Complemento (apartamento, sala, bloco). Opcional. Ex.: `Apto 51`. **neighborhood** `string` Bairro. Opcional. Ex.: `Bela Vista`. **city** `string` *required* Cidade. Ex.: `São Paulo`. **state** `string` *required* Estado (UF). Ex.: `SP`. **country** `string` *required* País no padrão ISO 3166-1 alpha-3. Ex.: `BRA`. Envie em maiúsculas: o valor volta nos webhooks exatamente como foi enviado. **trackingInfo** `object` Dados de rastreio do envio. **propriedades** **trackingCode** `string` Código de rastreio da transportadora. Ex.: `BR123456789BR`. **shippingProvider** `string` Nome da transportadora. Ex.: `Correios`. **trackingUrl** `string` Link para acompanhar a entrega. **trackingStatus** `string` Situação da entrega: `awaiting_shipment`, `on_the_way` ou `delivered`. **metadata** `object` Informações suas, em formato livre, que ficam guardadas na cobrança. Ex.: `{"orderId": "ORD-123"}`. Use chaves em camelCase, que voltam iguais em todos os canais. Chaves em snake\_case voltam convertidas para camelCase nas respostas de `GET` e no `charge.updated`. Veja [Metadata](/guias/cobrancas/visao-geral#metadata). **postbackUrl** `string` URL (formato `uri`) que recebe, de forma assíncrona, os eventos desta cobrança. Ela não muda a resposta da criação. Ex.: `https://meusite.com.br/webhooks/finvia`. A `postbackUrl` recebe os mesmos eventos de cobrança que os endpoints de webhook do painel, no envelope padrão (`id`, `event`, `livemode`, `data`): `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback` e `charge.blocked`. Não há filtro de eventos nesse canal. Ela recebe também o `charge.updated` legado, que vai **só** para a `postbackUrl`, em camelCase e sem `id` nem `livemode`. Veja a [tabela de eventos por canal](/guias/webhooks/visao-geral#eventos-por-canal). **split** `object[]` Divisão do valor entre contas do mesmo grupo Connect. Se você não enviar `split`, a API aplica a regra de split padrão da conta para aquela moeda e método, quando houver uma. **propriedades** **merchantId** `string` Conta que vai receber a parte. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **percentage** `number` Percentual destinado a essa conta. Mínimo `0.01`, máximo `100`. > [!NOTE] > > **Para o negócio:** por padrão, o percentual do split incide sobre o **valor líquido** da cobrança, isto é, o valor menos a taxa transacional (fixa + percentual). O uso do valor bruto é configurado pela Finvia, sob consulta. O repasse acontece a cada parcela liquidada. Prazos e exemplos em [Split](/guias/fast-connect/split) e [Cálculo de split](/guias/fast-connect/calculo-split). ## Formas de pagamento | Formato | `type` | Campos obrigatórios | Uso típico | | - | - | - | - | | Cartão de crédito | `credit_card` | `number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`, `installments` | Checkout com digitação do cartão | | Cartão salvo | `credit_card` | `cardTokenId`, `cvv`, `installments` | Recompra com um clique | | Apple Pay | `credit_card` | `wallet`, `installments` | Checkout web com Apple Pay | | Pix | `pix` | `type` e `expirationInDays` ou `expirationInSeconds` | Pagamento instantâneo | ### Cartão de crédito **paymentMethod.type** `string` *required* `credit_card`. **paymentMethod.number** `string` *required* Número do cartão, só com dígitos e sem espaços. Ex.: `4444333322221111`. **paymentMethod.holderName** `string` *required* Nome impresso no cartão. Ex.: `MARIA SOUZA`. **paymentMethod.expirationMonth** `string` *required* Mês de validade com 2 caracteres (`minLength` 2, `maxLength` 2). Ex.: `10`. **paymentMethod.expirationYear** `string` *required* Ano de validade com 4 caracteres (`minLength` 4, `maxLength` 4). Ex.: `2028`. **paymentMethod.cvv** `string` *required* Código de segurança. Mínimo de 3 caracteres. **paymentMethod.installments** `integer` *required* Número de parcelas. Mínimo `1`, máximo `12`. Valor `0`, negativo ou acima de `12` recebe `400`. **paymentMethod.threeDSMode** `string` Use `managed` para a Finvia conduzir a autenticação 3D Secure. Com esse valor, envie também `browser` e não envie `threeDS`. O 3DS só começa quando a política 3DS da sua conta dispara (3DS habilitado e obrigatório, ou valor igual ou acima do mínimo configurado). A partir daí: * Se o emissor pedir verificação do dispositivo ou desafio, a resposta vem com `status` `authentication_required`, `reason` `Autenticação 3DS gerenciada necessária` e `authenticationUrl`. * Na autenticação sem atrito (frictionless), a cobrança segue direto e a resposta já traz o status final. * Sem `browser`, ou se o serviço de 3DS falhar, a cobrança segue sem 3DS. Se o 3DS for obrigatório para a conta, ela é recusada. Veja [3DS gerenciado](/guias/3d-secure/gerenciado). **paymentMethod.browser** `object` Dados do navegador do comprador, usados na autenticação 3DS (schema `BrowserInfo`). **propriedades** **userAgent** `string` *required* User agent do navegador. **ipAddress** `string` *required* IP do comprador (IP válido). Ex.: `177.128.144.97`. **acceptHeader** `string` Valor do cabeçalho Accept do navegador. **language** `string` Idioma do navegador. Ex.: `pt-BR`. **timezoneOffset** `integer` Diferença do fuso em minutos em relação ao UTC. Ex.: `-180`. **javascriptEnabled** `boolean` Se o JavaScript está habilitado. **javaEnabled** `boolean` Se o Java está habilitado. **screenWidth** `integer` Largura da tela em pixels. **screenHeight** `integer` Altura da tela em pixels. **colorDepth** `integer` Profundidade de cor da tela, em bits. **paymentMethod.threeDS** `object` Resultado de uma autenticação 3DS feita por você antes da cobrança (schema `CreditCardThreeDS`), pelo [SDK](/guias/3d-secure/sdk) ou [via API](/guias/3d-secure/via-api). Repasse o objeto recebido em `POST /v1/three-ds/challenge-result`. Nos campos opcionais, **omita o campo quando não tiver valor e não envie `null`**: o `null` é gravado e repassado ao adquirente. **propriedades** **type** `string` *required* Tipo de autenticação 3DS (ex.: `full`). **state** `string` *required* Resultado da autenticação: `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled`. Só `success` permite seguir com a cobrança quando o 3DS é obrigatório para a conta. **cryptogram** `string` CAVV (valor de autenticação) em Base64. Com `state``success`, envie sempre. **eci** `string` Electronic Commerce Indicator. Valores comuns: `05` (autenticado), `06` (tentativa), `07` (não autenticado). Com `state``success`, envie sempre. **version** `string` Versão do protocolo 3DS (ex.: `2.2.0`). **directoryServerTransactionId** `string` ID da transação no Directory Server (bandeira). **threeDsServerTransactionId** `string` ID da transação no 3DS Server. **acsTransactionId** `string` ID da transação no ACS (banco emissor). > [!NOTE] > > O contrato também lista em `threeDS` os campos `mode`, `deviceData` e `challenge.returnUrl`. No 3DS da Finvia (SDK, via API ou gerenciado) eles não têm uso: não envie. ### Cartão salvo Usa um cartão guardado no cofre da Finvia. O `cardTokenId` é o campo `id` devolvido por [`POST /v1/cards`](/referencia/cartoes/registrar). > [!WARNING] > > O **CVV do comprador é obrigatório em toda cobrança** com `cardTokenId`. Sem ele, a API responde `400` `CVV is required when using cardTokenId`. Esta rota não faz cobrança com o comprador ausente. Para cobrar automaticamente a cada ciclo, use [Assinaturas](/referencia/assinaturas/criar). **paymentMethod.type** `string` *required* `credit_card`. **paymentMethod.cardTokenId** `string` *required* ID do cartão salvo (resposta de `POST /v1/cards`). Cartão revogado ou expirado recebe `400`. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **paymentMethod.cvv** `string` *required* Código de segurança, obrigatório mesmo para cartão salvo. Mínimo de 3 caracteres. **paymentMethod.installments** `integer` *required* Número de parcelas. Mínimo `1`, máximo `12`. **paymentMethod.threeDSMode** `string` `managed` para 3DS gerenciado. Envie `browser` junto. Os campos `browser` e `threeDS` também são aceitos, com as mesmas regras do cartão digitado. > [!NOTE] > > No Modo Teste (`sk_test_`), a cobrança com `cardTokenId` é simulada e não movimenta dinheiro. O cofre de cartões é o mesmo para teste e produção: o mesmo `cardTokenId` usado com a chave de produção gera uma cobrança real. Veja [Cartão salvo](/guias/cobrancas/cartao-salvo). ### Apple Pay Envie em `wallet.token` o objeto `payment.token` devolvido pelo Apple Pay JS no evento `onpaymentauthorized`, **sem alterações**. Com `wallet`, os campos do cartão (`number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`) não são exigidos. * Só a versão `EC_v1` é aceita. * A moeda precisa ser `BRL` (erro `APPLE_PAY_CURRENCY_NOT_SUPPORTED`). * `customer.document` é obrigatório (erro `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED`). * O 3D Secure não se aplica: a autenticação já vem no token. A Finvia não decifra o token, ele é repassado ao processador. * Antes de cobrar, registre e verifique o domínio ([`POST /v1/apple-pay/domains`](/referencia/apple-pay/registrar-dominio)) e valide a sessão ([`POST /v1/apple-pay/validate-merchant`](/referencia/apple-pay/validar-sessao)). O passo a passo está no [guia de Apple Pay](/guias/cobrancas/apple-pay). **paymentMethod.type** `string` *required* `credit_card`. **paymentMethod.installments** `integer` *required* Número de parcelas. Mínimo `1`, máximo `12`, a mesma regra do cartão digitado. **paymentMethod.wallet** `object` *required* Payload da carteira Apple Pay com o token seguro. **propriedades** **type** `string` *required* `applepay`. **token** `object` *required* Token de pagamento do Apple Pay, enviado como veio da Apple. **propriedades** **paymentData** `object` *required* Dados de pagamento criptografados. **propriedades** **data** `string` *required* Dados criptografados em Base64 (formato `byte`). **signature** `string` *required* Assinatura PKCS #7 destacada (detached), codificada em Base64 (formato `byte`). **version** `string` *required* Versão do formato do token: `EC_v1`. **header** `object` *required* Cabeçalho com dados de troca de chaves. **propriedades** **ephemeralPublicKey** `string` *required* Chave pública efêmera EC em Base64 (formato `byte`). **publicKeyHash** `string` *required* Hash SHA-256 do certificado da chave pública do merchant, em Base64 (formato `byte`). **transactionId** `string` *required* Identificador da transação em hexadecimal. **paymentMethod** `object` *required* Dados do cartão usado. **propriedades** **displayName** `string` *required* Descrição do cartão. Ex.: `Visa 1234`. **network** `string` *required* Bandeira. Ex.: `Visa`. **type** `string` *required* Tipo do cartão: `debit`, `credit`, `prepaid` ou `store`. **transactionIdentifier** `string` *required* Identificador único da transação Apple Pay. ### Pix **paymentMethod.type** `string` *required* `pix`. **paymentMethod.expirationInDays** `number` Validade em dias. Mínimo `1`. Obrigatório se `expirationInSeconds` não for enviado. **paymentMethod.expirationInSeconds** `number` Validade em segundos. Mínimo `900` (15 minutos). Obrigatório se `expirationInDays` não for enviado. Como escolher a validade para cada cenário: veja o [guia de Pix](/guias/cobrancas/pix#como-escolher-a-validade). No Modo Teste, o Pix é confirmado sozinho cerca de 5 segundos depois da criação. ## Respostas A resposta `201` tem sempre `id`, `status`, `paymentDetails` e `reason`. `authenticationUrl` e `customerId` aparecem só em alguns casos. **id** `string` *required* Identificador único da cobrança criada. Guarde este valor: ele é usado para consultar, estornar e conciliar a cobrança com os webhooks. **status** `string` *required* Situação da cobrança na criação: `paid`, `pending`, `refused`, `failed`, `in_analysis` ou `authentication_required`. Os status `refunded`, `pre_chargeback` e `chargeback` nunca saem na criação. **paymentDetails** `object | null` *required* Detalhes específicos da forma de pagamento. Vem `null` em recusas e quando o status é `authentication_required`. **Cartão de crédito** **firstSix** `string` *required* Seis primeiros dígitos do cartão. **lastFour** `string` *required* Quatro últimos dígitos do cartão. **expirationMonth** `string` *required* Mês de validade. **expirationYear** `string` *required* Ano de validade. **holderName** `string` *required* Nome do titular. **installments** `number` *required* Número de parcelas usado. **brand** `string` Bandeira do cartão. Opcional; aparece no Apple Pay. **Pix** **copyPaste** `string` *required* Código Pix "copia e cola" (BR Code EMV). O pagador cola no app do banco para pagar. **qrCodeBase64** `string | null` Imagem do QR Code (PNG, 256x256) em data URI, gerada a partir do `copyPaste`. Pode ser usada direto no `src` de uma tag ``. Vem `null` ou ausente quando o QR Code não pôde ser gerado; nesse caso, mostre o `copyPaste`. **endToEndId** `string` Identificador End to End do Pix, preenchido quando o pagamento é confirmado. **expiresAt** `string` Data e hora de expiração do Pix, em ISO 8601. Opcional. **reason** `string | null` *required* Motivo do status. Em recusas, explica a causa (ex.: `card_declined`, ou um texto iniciado em `3ds_` quando a recusa vem da autenticação). Em `in_analysis`, vem `antifraud_manual_review`. Em `authentication_required` no 3DS gerenciado, vem `Autenticação 3DS gerenciada necessária`. **authenticationUrl** `string` Endereço para onde o comprador deve ir para concluir a autenticação. Vem só quando `status` é `authentication_required`. Use exatamente o valor recebido, sem montar nem alterar a URL. Além do 3DS gerenciado, alguns adquirentes também podem pedir autenticação do lado deles e devolver este campo. **customerId** `string` ID do cliente criado ou reaproveitado na cobrança. Vem quando a cobrança chega ao adquirente ou é recusada por valor máximo. Não vem quando a cobrança é barrada antes: pelo antifraude (`refused` ou `in_analysis`), pela validação de 3DS obrigatório ou quando vai para o 3DS gerenciado (`authentication_required`). | `status` na criação | O que significa | O que fazer | | - | - | - | | `paid` | Pagamento aprovado | Confirmar o pedido | | `pending` | Aguardando pagamento (Pix gerado) ou pendente no adquirente | Aguardar `charge.paid` | | `refused` | Recusada (emissor, antifraude ou 3DS obrigatório) | Mostrar `reason` e oferecer outra forma de pagamento | | `failed` | Falha no processamento | Oferecer nova tentativa ou outra forma de pagamento | | `in_analysis` | Enviada para revisão manual do antifraude | Aguardar. O desfecho chega pelo `charge.updated` na `postbackUrl` ou pela consulta | | `authentication_required` | Aguardando autenticação do comprador | Levar o comprador à `authenticationUrl` | | HTTP | Significado | Corpo | | - | - | - | | `201` | Cobrança criada. Uma recusa também volta como `201`: leia `status` | `id`, `status`, `paymentDetails`, `reason` e, quando houver, `authenticationUrl` e `customerId` | | `400` | Corpo inválido. Inclui item `physical` sem `shippingAddress`, `cardTokenId` sem `cvv`, e os códigos `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` e `APPLE_PAY_TOKEN_INVALID` | Erro de validação com `message` em lista, ou mensagem única | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Perfil do usuário dono da chave sem permissão | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` | | `422` | Regra de negócio: `Fees not configured` (sem taxa para o método e a moeda) ou `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | Mensagem do erro | | `500` | Erro interno | `{"statusCode": 500, "message": "Internal server error"}` | Trate o erro pelo código HTTP (e pelo código `APPLE_PAY_*`, quando houver), não pelo texto: as mensagens da API misturam português e inglês. > [!NOTE] > > **Para o negócio:** no cartão, aprovação e recusa voltam **na própria resposta** da criação. Se `status` vier `refused`, o campo `reason` explica o motivo e o checkout pode oferecer outra forma de pagamento sem sair da página. No Pix, a resposta traz o QR Code com `status` `pending`, e a confirmação do pagamento chega depois, por webhook. ## Exemplos por caso de uso > [tab] Pix (infoproduto) > > Venda de um curso online. Produto digital, sem endereço de entrega. O Pix expira em 1 hora. > > ```json theme={null} > { > "amount": 297, > "currency": "BRL", > "customer": { > "name": "Joao Silva", > "email": "joao@email.com", > "document": { "type": "cpf", "id": "52998224725" }, > "phone": "+5511987654321", > "address": { "country": "BRA" } > }, > "paymentMethod": { "type": "pix", "expirationInSeconds": 3600 }, > "items": [ > { > "title": "Curso de Excel Avançado", > "type": "digital", > "description": "Acesso ao curso por 12 meses", > "unit_price": 297, > "quantity": 1 > } > ], > "metadata": { "orderId": "ORD-123" }, > "postbackUrl": "https://meusite.com.br/webhooks/finvia" > } > ``` > > Libere o acesso ao curso só depois de receber `charge.paid` e confirmar o status com [`GET /v1/charges/{id}`](/referencia/cobrancas/consultar). > [tab] Cartão parcelado (e-commerce) > > Produto físico em 3x, com endereço de entrega. > > ```json theme={null} > { > "amount": 599.7, > "currency": "BRL", > "customer": { > "name": "Maria Souza", > "email": "maria@email.com", > "document": { "type": "cpf", "id": "52998224725" }, > "ipAddress": "177.128.144.97" > }, > "paymentMethod": { > "type": "credit_card", > "number": "4444333322221111", > "holderName": "MARIA SOUZA", > "expirationMonth": "10", > "expirationYear": "2028", > "cvv": "123", > "installments": 3 > }, > "items": [ > { "title": "Tênis de corrida", "type": "physical", "description": "Tamanho 38", "unit_price": 199.9, "quantity": 3 } > ], > "shippingAddress": { > "postalCode": "01310100", > "addressLine1": "Av. Paulista, 1000", > "addressLine2": "Apto 51", > "neighborhood": "Bela Vista", > "city": "São Paulo", > "state": "SP", > "country": "BRA" > }, > "metadata": { "orderId": "ORD-3091" } > } > ``` > [tab] Cartão salvo (recompra) > > ```json theme={null} > { > "amount": 89.9, > "currency": "BRL", > "customer": { "id": "2RhQgK4vN8pT1wZ6yB3mC7dF" }, > "paymentMethod": { > "type": "credit_card", > "cardTokenId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "cvv": "123", > "installments": 1 > }, > "items": [ > { "title": "Refil de filtro", "type": "physical", "description": "Refil trimestral", "unit_price": 89.9, "quantity": 1 } > ], > "shippingAddress": { > "postalCode": "01310100", > "addressLine1": "Av. Paulista, 1000", > "city": "São Paulo", > "state": "SP", > "country": "BRA" > } > } > ``` > [tab] Split (marketplace) > > Venda criada com a chave da subconta do vendedor, separando 10% para outra conta do mesmo grupo Connect. > > ```json theme={null} > { > "amount": 100, > "currency": "BRL", > "customer": { "name": "Ana Lima", "email": "ana@email.com" }, > "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 }, > "items": [ > { "title": "Aula de cerâmica online", "type": "digital", "description": "Turma de sábado", "unit_price": 100, "quantity": 1 } > ], > "split": [ > { "merchantId": "2vorkDcXyvzifL63YX09S9VqcnI", "percentage": 10 } > ] > } > ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie o endereço com `postalCode`, `addressLine1`, `city`, `state` e `country` | | `400` com `shippingAddress.country must be a valid ISO31661 Alpha3 code` | País em duas letras (`BR`) | Envie o código de três letras: `BRA` | | `400` com `CVV is required when using cardTokenId` | Cobrança com cartão salvo sem `cvv` | Peça o CVV ao cliente em toda compra | | `400` de validação em `installments` | Parcelas `0`, negativas ou acima de `12` | Envie um inteiro de `1` a `12` | | `422` com `Fees not configured` | A conta não tem taxa para o método e a moeda | Fale com o suporte da Finvia para configurar a taxa | | Valor cobrado 100 vezes maior | `amount` enviado em centavos | Envie em reais: `10` = R\$ 10,00 | | `403` ao criar cobrança | Perfil do usuário que gerou a chave | Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave) | | Cobrança duplicada após timeout | Reenvio do POST sem verificar se a primeira foi criada | Siga o [procedimento para timeout](/primeiros-passos/paginacao-ordenacao-idempotencia#idempotência) | | Apple Pay recusado com `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | Moeda diferente de `BRL` | Envie `currency` `BRL` | | Apple Pay recusado com `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` | `customer.document` ausente | Envie o CPF ou CNPJ do cliente | ```http REST (JSON) theme={null} POST /v1/charges HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }' ``` ```javascript Node.js theme={null} // criar-cobranca.mjs (Node.js 18+, ESM, await no topo) const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 100, currency: 'BRL', customer: { name: 'Joao Silva', email: 'joao@email.com' }, paymentMethod: { type: 'pix', expirationInDays: 1 }, items: [ { title: 'Produto XYZ', type: 'digital', description: 'Descrição do produto', unit_price: 100, quantity: 1 }, ], metadata: { orderId: 'ORD-123' }, }), }); const charge = await response.json(); console.log(charge.id, charge.status); ``` ```python Python theme={null} import os import requests payload = { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725", }, "phone": "+5511987654321", "address": { "country": "BRA", }, }, "paymentMethod": { "type": "pix", "expirationInDays": 1, }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1, }, ], "metadata": { "orderId": "ORD-123", }, "postbackUrl": "https://meusite.com.br/webhooks/finvia", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 100, 'currency' => 'BRL', 'customer' => [ 'name' => 'Joao Silva', 'email' => 'joao@email.com', 'document' => [ 'type' => 'cpf', 'id' => '52998224725', ], 'phone' => '+5511987654321', 'address' => [ 'country' => 'BRA', ], ], 'paymentMethod' => [ 'type' => 'pix', 'expirationInDays' => 1, ], 'items' => [ [ 'title' => 'Produto XYZ', 'type' => 'digital', 'description' => 'Descrição do produto', 'unit_price' => 100, 'quantity' => 1, ], ], 'metadata' => [ 'orderId' => 'ORD-123', ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 100, "currency": "BRL", "customer": { "name": "Joao Silva", "email": "joao@email.com", "document": { "type": "cpf", "id": "52998224725" }, "phone": "+5511987654321", "address": { "country": "BRA" } }, "paymentMethod": { "type": "pix", "expirationInDays": 1 }, "items": [ { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 } ], "metadata": { "orderId": "ORD-123" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 100, "currency" => "BRL", "customer" => { "name" => "Joao Silva", "email" => "joao@email.com", "document" => { "type" => "cpf", "id" => "52998224725", }, "phone" => "+5511987654321", "address" => { "country" => "BRA", }, }, "paymentMethod" => { "type" => "pix", "expirationInDays" => 1, }, "items" => [ { "title" => "Produto XYZ", "type" => "digital", "description" => "Descrição do produto", "unit_price" => 100, "quantity" => 1, }, ], "metadata" => { "orderId" => "ORD-123", }, "postbackUrl" => "https://meusite.com.br/webhooks/finvia", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 Pix theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "pending", "paymentDetails": { "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD", "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo..." }, "reason": null, "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q" } ``` ```json 201 Cartão theme={null} { "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE", "status": "paid", "paymentDetails": { "firstSix": "444433", "lastFour": "1111", "expirationMonth": "10", "expirationYear": "2028", "holderName": "MARIA SOUZA", "installments": 3 }, "reason": "success", "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q" } ``` ```json 201 3DS gerenciado theme={null} { "id": "2vorkQw7Ns2RtY5uIo9Pa3SdFgH", "status": "authentication_required", "paymentDetails": null, "reason": "Autenticação 3DS gerenciada necessária", "authenticationUrl": "https://" } ``` ```json 400 Endereço ausente theme={null} { "message": "Shipping info must be provided for merchants selling physical items.", "error": "Bad Request", "statusCode": 400 } ``` ```json 400 Validação theme={null} { "statusCode": 400, "message": ["shippingAddress.country must be a valid ISO31661 Alpha3 code"], "error": "Bad Request" } ``` ## Veja também > [card] [Consultar cobrança](/referencia/cobrancas/consultar) > > Status atual e detalhes de uma cobrança. > [card] [Estornar cobrança](/referencia/cobrancas/estornar) > > Estorno total de uma cobrança paga. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos do ciclo de vida da cobrança. > [card] [Homologação](/homologacao/roteiro) > > Cenários CHG-01 a CHG-10 e SPL-01 a SPL-06. # Estornar uma cobrança Source: https://docs.fastpaybrasil.com/referencia/cobrancas/estornar POST /v1/refunds Solicita o estorno total de uma cobrança paga, em Pix ou cartão de crédito. Esta rota devolve ao cliente o valor **inteiro** de uma cobrança paga. Ela atende cancelamento de pedido, desistência de compra, produto indisponível depois da venda e qualquer outro caso em que o dinheiro precisa voltar ao comprador. Funciona para cobranças pagas com Pix e com cartão de crédito (inclusive cartão salvo e Apple Pay). > [!WARNING] > > Esta rota é o **único caminho para pedir um estorno**. A Finvia não faz estorno por chamado ou pelo suporte, exceto em caso de erro sistêmico. Integre esta chamada ao seu sistema ou ao seu processo de atendimento. ## Quando usar | Situação | Como usar esta rota | | - | - | | Cliente cancelou o pedido | Envie o `chargeId` e o motivo do cancelamento | | Produto sem estoque depois da venda | Estorne e registre o motivo para auditoria | | Cobrança duplicada por erro da sua integração | Estorne a cobrança repetida | | Devolver só parte do valor | Não é possível. A API faz apenas estorno total | | Assinatura cancelada em até 7 dias | O cancelamento da assinatura já estorna as cobranças pagas. Veja [Cancelar assinatura](/referencia/assinaturas/cancelar) | ## Antes de chamar * Tenha uma chave secreta do mesmo ambiente da cobrança ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * A cobrança precisa estar com `status` `paid`. Confira com [`GET /v1/charges/{id}`](/referencia/cobrancas/consultar). Uma cobrança bloqueada (`isBlocked: true`) continua `paid` e pode ser estornada. * O pedido precisa partir da conta dona da cobrança. Em venda com split, o recebedor não consegue estornar. * Cada cobrança aceita **um único estorno**. ## Corpo da requisição Os dois campos são obrigatórios. **chargeId** `string` *required* ID da cobrança a ser estornada. A cobrança precisa estar com status `paid`. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **reason** `string` *required* Motivo do estorno, em texto livre. Fica registrado para auditoria. Ex.: `Pedido ORD-123 cancelado pelo cliente`. ## Respostas **status** `string` Resultado do estorno. Hoje a API devolve sempre `refunded`: o estorno foi registrado na Finvia e o valor saiu do seu saldo. **reason** `string | null` Texto informado pelo provedor de pagamento (PSP). Pode vir preenchido mesmo quando o estorno deu certo: decida pelo `status`, não por este campo. **pspRefundRefId** `string | null` Identificador do estorno no PSP, quando disponível. Ex.: `ref_abc123`. Com o `201`, a cobrança passa a `refunded` e o webhook `charge.refunded` é enviado aos endpoints do painel e à `postbackUrl` da cobrança. Se a adquirente ou o banco não concluir o estorno automaticamente, a API responde `refunded` mesmo assim e a equipe Finvia conclui o estorno manualmente. Nesse caso o comprador pode demorar mais para receber. Não reenvie o pedido: se o comprador não receber, acione o suporte com o `chargeId`. | HTTP | Significado | `message` | | - | - | - | | `201` | Estorno registrado | Corpo com `status`, `reason`, `pspRefundRefId` | | `400` | Corpo inválido (campo ausente ou de tipo errado) | Lista de mensagens de validação | | `401` | Credencial inválida | `Unauthorized` | | `403` | Perfil do usuário dono da chave sem permissão | `Acesso negado` | | `404` | Cobrança inexistente ou que não está `paid` (pendente, já estornada, `pre_chargeback`, `chargeback` e outros) | `Cobrança não encontrada` | | `422` | Já existe um estorno para esta cobrança | `Já existe um reembolso para esta cobrança` | | `501` | Método de pagamento ou provedor sem estorno | `Reembolso não implementado para este método de pagamento` ou `Reembolso não disponível para este provedor de pagamento` | | `500` | Erro interno | | Os erros seguem o formato padrão, com `statusCode`, `message` e `error`. Trate pelo código HTTP, não pelo texto. > [!NOTE] > > **Para o negócio:** o comprador recebe o valor integral da cobrança. Do seu saldo sai o valor bruto da venda, e as taxas da venda não são devolvidas. Prazos para o comprador receber, efeito no split e estorno depois do saque estão no [guia de estorno](/guias/estorno). ## Evite estorno duplicado A API não aceita o cabeçalho `Idempotency-Key`, mas recusa um segundo estorno da mesma cobrança. A proteção fica assim: **1. Grave o resultado** Ao receber o `201`, grave o `status` e o `pspRefundRefId` junto com a cobrança. A resposta não traz um campo `id` do estorno. **2. Trate o 422 como final** `422` `Já existe um reembolso para esta cobrança` indica que o estorno já foi feito. Não repita o pedido. **3. Depois de um timeout, consulte a cobrança** Chame `GET /v1/charges/{id}`. Se ela estiver `refunded`, grave o resultado e não envie outro pedido. O [guia de estorno](/guias/estorno) traz uma rotina completa em Node.js. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `Cobrança não encontrada` para uma cobrança que existe | A cobrança não está `paid` (pendente, já estornada, em `pre_chargeback` ou `chargeback`) ou é de outro ambiente | Consulte a cobrança. Só cobranças `paid` podem ser estornadas | | `422` no segundo pedido | A cobrança já tem um estorno | Não reenvie. Acompanhe pelo `charge.refunded` ou pela consulta | | `501` | Método ou provedor sem estorno pela API | Só Pix e cartão têm estorno | | `403` | A chave herda as permissões do usuário que a gerou | Confira o perfil do usuário que gerou a chave ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)) | | Esperava devolver parte do valor | A rota faz só estorno total | Não há estorno parcial na API | | Recebedor do split não consegue estornar | O estorno é pedido pela conta dona da cobrança | Peça o estorno com a chave do originador | ## Como testar No sandbox, com a chave `sk_test_`: * **CHG-07:** estorno total de uma cobrança paga. Resultado esperado: status `refunded` e webhook `charge.refunded`. * **AP-05:** estorno de uma cobrança Apple Pay paga, se você usa Apple Pay. Detalhes e evidências em [Roteiro de homologação](/homologacao/roteiro). ```http REST (JSON) theme={null} POST /v1/refunds HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/refunds" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/refunds', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ chargeId: '2vorkDcXyvzifL63YX09S9VqcnI', reason: 'Pedido ORD-123 cancelado pelo cliente', }), }); if (response.status === 201) { const refund = await response.json(); console.log('Estorno registrado:', refund.status, refund.pspRefundRefId); } else if (response.status === 422) { console.log('A cobrança já tinha um estorno. Nada a fazer.'); } else { const erro = await response.json(); console.warn('Estorno não aceito:', response.status, erro.message); } ``` ```python Python theme={null} import os import requests payload = { "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/refunds", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2vorkDcXyvzifL63YX09S9VqcnI', 'reason' => 'Pedido ORD-123 cancelado pelo cliente', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/refunds'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/refunds")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/refunds"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI", "reason": "Pedido ORD-123 cancelado pelo cliente" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/refunds", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/refunds") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "chargeId" => "2vorkDcXyvzifL63YX09S9VqcnI", "reason" => "Pedido ORD-123 cancelado pelo cliente", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "status": "refunded", "reason": null, "pspRefundRefId": "ref_abc123" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Cobrança não encontrada", "error": "Not Found" } ``` ```json 422 theme={null} { "statusCode": 422, "message": "Já existe um reembolso para esta cobrança", "error": "Unprocessable Entity" } ``` ## Veja também > [card] [Guia de estorno](/guias/estorno) > > Prazos, saldo, split e estorno depois do saque. > [card] [Consultar cobrança](/referencia/cobrancas/consultar) > > Confira o status antes e depois do estorno. > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Payload do evento `charge.refunded`. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > Quando o estorno vem de uma contestação. # Listar cobranças Source: https://docs.fastpaybrasil.com/referencia/cobrancas/listar GET /v1/charges Lista as cobranças da sua conta em páginas, da mais recente para a mais antiga, com filtros por status, moeda, período e busca por texto. Esta rota devolve as cobranças (charges) da sua conta em páginas. Ela serve para montar telas de acompanhamento, fazer conciliação diária, encontrar cobranças em um status específico (por exemplo, tudo o que está em `pre_chargeback` ou bloqueado) e localizar uma cobrança depois de um timeout na criação. ## Quando usar | Situação | Como usar esta rota | | - | - | | Tela de vendas no seu sistema | Liste sem filtros: a ordem é sempre da mais recente para a mais antiga | | Conciliação do dia | `status=paid` com `createdAtStart` e `createdAtEnd` no mesmo dia, percorrendo as páginas | | Acompanhar contestações | `status=pre_chargeback`, `status=chargeback` ou `status=blocked` | | Achar a cobrança depois de um timeout na criação | `createdAtStart` + `createdAtEnd` do dia e `searchFor` com o documento ou o e-mail do comprador | | Saber o status atual de **uma** cobrança | Use [`GET /v1/charges/{id}`](/referencia/cobrancas/consultar), que é mais direto | > [!NOTE] > > Não há filtro por `metadata`, pelo número do seu pedido nem por valor. Para localizar uma cobrança, combine o período com `searchFor` e compare `metadata` e `amount` do seu lado. O procedimento completo para timeout está em [Idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia#idempotência). ## Antes de chamar * Tenha uma chave secreta (`sk_` ou `sk_test_`) ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * A chave de teste lista só as cobranças de teste; a chave de produção lista só as cobranças reais. ## Parâmetros de consulta Nenhum parâmetro é obrigatório. Sem parâmetros, a rota devolve a primeira página com 10 cobranças. **page** `integer` (default: 1) Número da página. Começa em `1`. **size** `integer` (default: 10) Quantidade de cobranças por página. Ex.: `50`. **status** `string` Filtra pelo status da cobrança: `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`, `pre_chargeback` ou `chargeback`. O valor `blocked` lista as cobranças bloqueadas (MED ou chargeback em análise), que continuam com status `paid`. **currency** `string` Filtra pela moeda, no padrão ISO 4217. Ex.: `BRL`. **createdAtStart** `string` Data inicial do período, no formato `AAAA-MM-DD`, sobre a data de criação. Envie **junto com** `createdAtEnd`. O filtro pega o dia inteiro, no fuso do servidor (UTC). Ex.: `2026-10-27`. **createdAtEnd** `string` Data final do período, no formato `AAAA-MM-DD`. Envie **junto com** `createdAtStart`. Ex.: `2026-10-27`. **merchantId** `string` Filtra pelo ID da conta dona da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **searchFor** `string` Busca parcial, sem diferenciar maiúsculas de minúsculas, em: nome, e-mail, documento e telefone do comprador; seis primeiros e quatro últimos dígitos do cartão; título do primeiro item; `pspRefId`; `endToEndId` do Pix; e nome da conta. Ex.: `52998224725`. > [!WARNING] > > A API ignora parâmetros desconhecidos sem dar erro. `orderBy`, `limit` ou `metadata` na URL não filtram nem ordenam nada, e a lista volta como se eles não existissem. Use só os parâmetros desta página. ### O que significa cada status | Status | Significado | | - | - | | `pending` | Aguardando pagamento (ex.: Pix gerado e ainda não pago) | | `paid` | Pago com sucesso | | `refused` | Recusado (emissor, antifraude ou 3DS obrigatório) | | `failed` | Falha no processamento | | `refunded` | Estornado | | `in_analysis` | Em análise antifraude | | `authentication_required` | Aguardando autenticação do comprador | | `pre_chargeback` | Alerta de pré-chargeback recebido antes de o chargeback ser formalizado | | `chargeback` | Chargeback formalizado | A explicação completa de cada status e das transições está em [Status de cobrança](/anexos/status-de-cobranca). ### Tentativas agrupadas No cartão, tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas. A listagem mostra **só a cobrança principal** do grupo. As demais tentativas aparecem em `groupCharges`, na [consulta da cobrança principal](/referencia/cobrancas/consultar). Leve isso em conta ao contar tentativas recusadas ou ao procurar uma cobrança específica. ## Respostas A resposta `200` traz a página pedida (`data`) e os totais para você navegar pelas demais páginas. **data** `object[]` Cobranças da página atual, da mais recente para a mais antiga. **propriedades da cobrança** **id** `string` Identificador único da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **status** `string` Status da cobrança (tabela acima). **chargebackAlertRefunded** `boolean | null` Em cobranças com alerta de pré-chargeback: `true` se o valor já foi estornado ao comprador, `false` se a disputa está aberta sem estorno. `null` quando não há alerta. **chargebackAlertReason** `string | null` Motivo ou referência informado no alerta de pré-chargeback. Ex.: `Chargeback - NSU 123456789`. **pspRefId** `string | null` Identificador da cobrança no provedor de pagamento (PSP). Ex.: `ch_123456789`. **amount** `number` Valor total da cobrança, em reais. Ex.: `100.5`. **currency** `string` Moeda no padrão ISO 4217. Ex.: `BRL`. **spread** `number` Spread (taxa) aplicado à cobrança. Ex.: `2.5`. **net** `number` Valor líquido depois do spread. Ex.: `98`. **customer** `object` Cliente: `id`, `name`, `email` e `document` (texto). **paymentMethod** `object` Forma de pagamento. No Pix, `type` `pix`. No cartão: `type`, `firstSix`, `lastFour`, `expirationMonth`, `expirationYear`, `holderName` e `installments`. **merchantId** `string` Identificador da conta dona da cobrança. **paymentDetails** `object | null` Detalhes do pagamento. No cartão: `firstSix`, `lastFour`, `expirationMonth`, `expirationYear`, `holderName`, `installments` e, no Apple Pay, `brand`. No Pix: `endToEndId`, `copyPaste`, `qrCodeBase64` e, opcionalmente, `expiresAt`. **metadata** `object | null` Informações livres enviadas na criação, com as chaves em **camelCase**: chaves enviadas em snake\_case chegam convertidas. Veja [Metadata](/guias/cobrancas/visao-geral#metadata). **paidAt** `string | null` Data e hora do pagamento, em ISO 8601. **createdAt** `string` Data e hora da criação, em ISO 8601. **updatedAt** `string` Data e hora da última atualização, em ISO 8601. **page** `integer` Número da página atual. Ex.: `1`. **pages** `integer` Total de páginas disponíveis. Ex.: `10`. **total** `integer` Total de cobranças somando todas as páginas. Ex.: `100`. **size** `integer` Quantidade de cobranças por página. Ex.: `10`. > [!NOTE] > > A lista de `splits` e as tentativas agrupadas (`groupCharges`) não vêm na listagem. Para ver a divisão do valor ou o bloqueio (`isBlocked`, `blockedAt`, `blockedReason`) de uma cobrança, use a [consulta individual](/referencia/cobrancas/consultar). | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista obtida | `data`, `page`, `pages`, `total`, `size` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Perfil do usuário dono da chave sem permissão | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` | > [!NOTE] > > **Para o negócio:** `amount` é o valor total da cobrança e `net` é o valor líquido depois do spread. Para acompanhar disputas, filtre por `blocked` (valor retido enquanto a disputa é analisada), `pre_chargeback` e `chargeback`. ## Percorrer todas as páginas Para exportar ou conciliar um volume grande, peça páginas até chegar ao valor de `pages`: ```javascript theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); async function listarDoDia(dia, status) { const todas = []; let page = 1; let pages = 1; do { const params = new URLSearchParams({ status, createdAtStart: dia, createdAtEnd: dia, page: String(page), size: '50', }); const res = await fetch(`https://api-global.fastpaybrasil.com/v1/charges?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); const body = await res.json(); todas.push(...body.data); pages = body.pages; page += 1; } while (page <= pages); return todas; } const pagas = await listarDoDia('2026-10-27', 'paid'); ``` > [!TIP] > > **Para o desenvolvedor:** se novas cobranças forem criadas enquanto você percorre as páginas, os itens mudam de posição e uma cobrança pode aparecer em duas páginas. Use o `id` para eliminar repetições e prefira filtrar por um período já encerrado. ## Exemplos por caso de uso > [tab] Vendas recentes > > As 20 cobranças mais novas, para uma tela de acompanhamento. > > ```bash theme={null} > curl "https://api-global.fastpaybrasil.com/v1/charges?page=1&size=20" \ > -u "$FINVIA_API_KEY:" > ``` > [tab] Depois de um timeout > > Cobranças criadas hoje para o comprador de CPF `52998224725`. Compare `metadata.orderId` e `amount` com o pedido que deu timeout. > > ```bash theme={null} > curl "https://api-global.fastpaybrasil.com/v1/charges?createdAtStart=2026-10-27&createdAtEnd=2026-10-27&searchFor=52998224725&size=50" \ > -u "$FINVIA_API_KEY:" > ``` > [tab] Cobranças bloqueadas > > Cobranças com bloqueio por MED ou chargeback, para a equipe de atendimento acompanhar. > > ```bash theme={null} > curl "https://api-global.fastpaybrasil.com/v1/charges?status=blocked" \ > -u "$FINVIA_API_KEY:" > ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` em toda chamada | Cabeçalho ausente, chave inválida ou Base64 sem os dois pontos no final | Decodifique o Base64 e confira se termina em `:` | | Lista vazia com vendas existentes | Chave de teste consultando vendas de produção, ou o contrário | Use a chave do mesmo ambiente em que as cobranças foram criadas | | Filtro de data não se comporta como esperado | Só um dos parâmetros `createdAtStart` e `createdAtEnd` foi enviado, ou a data veio em outro formato | Envie os dois juntos, no formato `AAAA-MM-DD` | | Ordenação ou tamanho ignorados | `orderBy` e `limit` não existem nesta rota | A ordem é fixa (mais recente primeiro). Para o tamanho, use `size` | | Uma tentativa recusada não aparece | Tentativas agrupadas aparecem só em `groupCharges` da principal | Consulte a cobrança principal | | `metadata.order_id` não encontrado | Chaves enviadas em snake\_case vêm em camelCase | Leia `metadata.orderId` ou envie as chaves em camelCase. Veja [Metadata](/guias/cobrancas/visao-geral#metadata) | ```http REST (JSON) theme={null} GET /v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20 HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl "https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const params = new URLSearchParams({ status: 'paid', createdAtStart: '2026-10-27', createdAtEnd: '2026-10-27', page: '1', size: '20', }); const response = await fetch(`https://api-global.fastpaybrasil.com/v1/charges?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); const { data, page, pages, total } = await response.json(); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges?status=paid&createdAtStart=2026-10-27&createdAtEnd=2026-10-27&page=1&size=20") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "data": [ { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "status": "paid", "chargebackAlertRefunded": null, "chargebackAlertReason": null, "pspRefId": "ch_123456789", "amount": 100.5, "currency": "BRL", "spread": 2.5, "net": 98, "customer": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Maria Souza", "email": "maria@email.com", "document": "529.982.247-25" }, "paymentMethod": { "type": "credit_card", "firstSix": "444433", "lastFour": "1111", "expirationMonth": "10", "expirationYear": "2028", "holderName": "MARIA SOUZA", "installments": 3 }, "merchantId": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH", "paymentDetails": { "firstSix": "444433", "lastFour": "1111", "expirationMonth": "10", "expirationYear": "2028", "holderName": "MARIA SOUZA", "installments": 3 }, "metadata": { "orderId": "ORD-3091" }, "paidAt": "2026-10-27T14:30:00Z", "createdAt": "2026-10-27T14:30:00Z", "updatedAt": "2026-10-27T14:30:00Z" } ], "page": 1, "pages": 10, "total": 100, "size": 10 } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" } ``` ## Veja também > [card] [Consultar cobrança](/referencia/cobrancas/consultar) > > Status, bloqueio, split e tentativas agrupadas de uma cobrança. > [card] [Status de cobrança](/anexos/status-de-cobranca) > > O que significa cada status e quando ele muda. > [card] [Paginação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia) > > Regras de `page` e `size` e o procedimento para timeout. > [card] [Bloqueio, chargeback e MED](/guias/bloqueio-chargeback-med) > > Como tratar contestações e bloqueios. # Reenviar webhook de teste Source: https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste POST /v1/charges/{id}/resend-webhook No Modo Teste, dispara um evento novo de uma cobrança de teste com o status que você escolher, para testar o seu tratamento de webhooks. Esta rota existe só para testes. Ela pega uma cobrança criada com a chave de teste e dispara um **evento novo**, `charge.{status}`, com o status que você escolher. Assim você testa como o seu sistema reage a um pagamento confirmado, a uma recusa ou a um estorno sem esperar o evento real acontecer. > [!NOTE] > > Apesar do nome da rota, ela não reenvia o evento original. Ela gera um evento simulado, com `id` novo, e **não altera a cobrança**: depois da chamada, `GET /v1/charges/{id}` continua mostrando o status real. ## Quando usar | Situação | Como usar esta rota | | - | - | | Testar a liberação do pedido após pagamento | Envie `status` `paid` | | Testar o cancelamento após estorno | Envie `status` `refunded` | | Testar o tratamento de recusa ou falha | Envie `refused` ou `failed` | | Testar um Pix que fica aguardando | Envie `pending` (no sandbox o Pix real é sempre confirmado) | | Validar a conectividade do endpoint antes de ir para produção | Envie qualquer status e confira `deliveries` na resposta | | Cobrança de produção | Não funciona. A rota aceita só cobranças de teste | > [!NOTE] > > **Para o negócio:** esta rota acelera a homologação. O time técnico simula cada situação e comprova que o sistema libera, cancela ou bloqueia pedidos do jeito certo. O cenário CHG-09 do roteiro de homologação pede essa evidência. ## Antes de chamar * Use a **chave de teste** (`sk_test_`) ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Tenha uma cobrança criada com essa chave de teste. Cobranças de produção recebem `403`. * Tenha um destino para o evento: um endpoint de webhook cadastrado na conta ou a `postbackUrl` informada na cobrança. ## Parâmetros de caminho **id** `string` *required* ID da cobrança de teste. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. ## Corpo da requisição **status** `string` *required* Status simulado. Define o evento enviado (`paid` gera `charge.paid`, `refunded` gera `charge.refunded` e assim por diante). Valores aceitos: `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis` e `authentication_required`. `pre_chargeback` e `chargeback` não são aceitos e recebem `400`. ## O que é enviado * Um evento `charge.{status}` novo, no envelope padrão, com `id` de evento novo e `livemode: false`. * Destinos: a `postbackUrl` da cobrança, se houver, e os endpoints de webhook da própria conta. * O payload simulado não é idêntico ao real: traz campos a mais e não traz `anticipation_fee_estimated`. Use esta rota para testar conectividade e o tratamento de cada evento. O formato de referência está em [Webhooks de cobrança](/guias/webhooks/cobranca). ## Respostas A resposta `201` traz o resultado da entrega em cada destino. **deliveries** `object[]` Uma entrada por destino notificado. **propriedades** **url** `string` Endereço notificado. **status** `integer` Código HTTP que o destino respondeu. **success** `boolean` `true` quando a entrega foi aceita (resposta 2xx). **error** `string` Descrição da falha. Opcional: vem só quando a entrega falhou. | HTTP | Significado | `message` | | - | - | - | | `201` | Evento disparado | Corpo com `deliveries` | | `400` | `status` fora da lista aceita | Lista de mensagens de validação | | `401` | Credencial inválida | `Unauthorized` | | `403` | A cobrança não é de teste, ou o perfil do usuário dono da chave não tem permissão | `Redisparo de webhook disponível apenas para cobranças de teste` ou `Acesso negado` | | `404` | Cobrança não encontrada | `Cobrança não encontrada` | > [!TIP] > > **Para o desenvolvedor:** o `201` confirma que a Finvia disparou o evento. Leia `deliveries` para saber se cada destino aceitou: `success: false` com `error` indica problema no seu endpoint. Para a evidência de homologação, guarde a resposta desta rota e o log do evento recebido. ## Roteiro de teste sugerido **1. Crie uma cobrança de teste** Crie uma cobrança com a chave `sk_test_` em [`POST /v1/charges`](/referencia/cobrancas/criar) e guarde o `id`. **2. Simule a recusa** Chame esta rota com `{"status": "refused"}` e confira se o seu sistema não liberou o pedido. **3. Simule o pagamento** Chame com `{"status": "paid"}` e confira se o seu sistema consultou a cobrança antes de liberar. **4. Simule o estorno** Chame com `{"status": "refunded"}` e confira se o pedido foi cancelado. **5. Repita um evento** Chame duas vezes com o mesmo status e confira se o pedido não foi processado em dobro. > [!TIP] > > O teste está completo quando, para cada status simulado, `deliveries` mostra `success: true` e o pedido mudou para a situação esperada no seu sistema. > [!WARNING] > > Como o evento simulado não altera a cobrança, um handler que confirma o status com `GET /v1/charges/{id}` antes de agir vai ver o status real da cobrança. Isso é o comportamento correto em produção. Para testar o caminho completo de um Pix pago, crie uma cobrança Pix com a chave de teste: ela é confirmada sozinha cerca de 5 segundos depois. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` com `Redisparo de webhook disponível apenas para cobranças de teste` | A cobrança foi criada com a chave de produção | Crie a cobrança com a chave `sk_test_` | | `400` ao simular `pre_chargeback` ou `chargeback` | Esses status não são aceitos nesta rota | Teste o tratamento com os payloads de exemplo do [guia de bloqueio](/guias/bloqueio-chargeback-med) | | Nenhum evento chega ao seu sistema | Nenhum endpoint cadastrado na conta e cobrança sem `postbackUrl` | Cadastre um endpoint no painel ou crie a cobrança com `postbackUrl` | | `success: false` em `deliveries` | O seu endpoint não respondeu 2xx | Leia `error` e confira se o endpoint está acessível pela internet | ## Como testar Este endpoint cobre o cenário **CHG-09** (simulação de webhook no sandbox) e apoia o **CHG-08** (recebimento de webhook) do [Roteiro de homologação](/homologacao/roteiro). ```http REST (JSON) theme={null} POST /v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "status": "paid" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "status": "paid" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ status: 'paid' }), }, ); const { deliveries } = await response.json(); for (const d of deliveries) { console.log(d.url, d.success ? 'entregue' : `falhou: ${d.error}`); } ``` ```python Python theme={null} import os import requests payload = { "status": "paid", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'paid', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "status": "paid" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "status": "paid" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "status": "paid" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "status" => "paid", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "deliveries": [ { "url": "https://meusite.com.br/webhooks/finvia", "status": 200, "success": true } ] } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Redisparo de webhook disponível apenas para cobranças de teste", "error": "Forbidden" } ``` ## Veja também > [card] [Webhooks de cobrança](/guias/webhooks/cobranca) > > Eventos e payloads reais de cobrança. > [card] [Visão geral de webhooks](/guias/webhooks/visao-geral) > > Como cadastrar e tratar webhooks. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > Gere a cobrança de teste. > [card] [Roteiro de homologação](/homologacao/roteiro) > > Cenários CHG-08 e CHG-09. # Chaves de API da subconta Source: https://docs.fastpaybrasil.com/referencia/fast-connect/chaves-de-api GET /v1/submerchants/{id}/api-keys Devolve a chave pública e a chave secreta de uma subconta ativa, para criar cobranças em nome do vendedor. Esta rota devolve as chaves de API (pública e secreta) de uma subconta (SubMerchant). Com a chave secreta da subconta, a sua plataforma cria cobranças **em nome do vendedor**: a venda fica registrada como originada pela subconta, e é a partir dela que o split distribui os valores. ## Quando usar | Situação | Como usar esta rota | | - | - | | Subconta acabou de ser aprovada (`active`) | Busque as chaves e guarde a secreta no seu cofre de segredos | | Criar cobranças vinculadas ao vendedor | Use a chave secreta da subconta em [`POST /v1/charges`](/referencia/cobrancas/criar) | | Apple Pay ou 3D Secure no checkout do vendedor | Use a chave pública (`pk_`) da subconta no front-end | | Cobranças em nome da própria conta master | Use a chave da conta master; esta rota não é necessária | ## Antes de chamar * Use as chaves para cobrar só depois que a subconta estiver **ativa** (`active`): antes da aprovação ela não está apta a transacionar. Confira com [Consultar subconta](/referencia/fast-connect/consultar-subconta). Se a API não encontrar chaves para a subconta, a rota devolve `404`. * Autentique com a chave secreta (`sk_`) da **conta master** ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). ## Parâmetros de caminho **id** `string` *required* Identificador único da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. ## Respostas **publicKey** `string` Chave pública da subconta. Pode ser usada no navegador, nas rotas que pedem a chave pública. Ex.: `pk_2vorkDcXyvzifL63YX09S9VqcnI`. **secretKey** `string` Chave secreta da subconta. Só pode ser usada no servidor. Ex.: `sk_2vorkDcXyvzifL63YX09S9VqcnI`. Em **modo de teste**, as chaves têm prefixo `sk_test_` e `pk_test_`. | HTTP | Significado | Corpo | | - | - | - | | `200` | Chaves devolvidas | `publicKey`, `secretKey` | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` | | `404` | Subconta não encontrada ou sem chaves de API | `{"statusCode": 404, "message": "API keys not found for this submerchant."}` | > [!WARNING] > > A chave **secreta** da subconta dá acesso às cobranças e aos dados dela. Guarde-a só no servidor, em um cofre de segredos, e nunca a envie ao navegador, ao aplicativo ou ao próprio vendedor por e-mail ou chat. A chave **pública** (`pk_`) é a que pode ir para o front-end. > [!NOTE] > > **Para o negócio:** para que cada venda fique ligada ao vendedor certo, a cobrança precisa ser criada com a chave secreta **da subconta que vendeu**. Com a chave da conta master, a venda fica registrada na própria conta master. As regras de quem pode enviar valor para quem estão em [Split de pagamentos](/guias/fast-connect/split). > [!TIP] > > **Para o desenvolvedor:** guarde a relação entre o `id` da subconta e a referência da chave no seu cofre. Na hora de cobrar, escolha a chave pelo vendedor do pedido. Se receber `404`, confira primeiro o `id` e o status da subconta. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` "API keys not found for this submerchant." | A API não encontrou chaves para a subconta | Confira o `id` e o status da subconta. Se persistir, fale com o suporte | | `404` com subconta ativa | `id` de outra conta master, inexistente ou de outro ambiente | Use o `id` correto e a chave da conta master no mesmo ambiente | | Cobrança registrada na conta master | Cobrança criada com a chave da conta master | Crie a cobrança com a chave secreta da subconta | ```http REST (JSON) theme={null} GET /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const id = '36OO3bcGjhPjjF3tzrqOGcmQuKo'; const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants/${id}/api-keys`, { headers: { Authorization: `Basic ${credentials}` }, }); if (response.status === 404) { // chaves não encontradas: confira o id e o status da subconta } else { const { publicKey, secretKey } = await response.json(); // grave secretKey no seu cofre de segredos, nunca em log } ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "publicKey": "pk_2vorkDcXyvzifL63YX09S9VqcnI", "secretKey": "sk_2vorkDcXyvzifL63YX09S9VqcnI" } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Fast Connect not enabled." } ``` ```json 404 theme={null} { "statusCode": 404, "message": "API keys not found for this submerchant." } ``` ## Veja também > [card] [Split de pagamentos](/guias/fast-connect/split) > > Divisão de valores entre contas do grupo. > [card] [Criar cobrança](/referencia/cobrancas/criar) > > Cobrança com a chave da subconta. > [card] [Consultar subconta](/referencia/fast-connect/consultar-subconta) > > Confirme que a subconta está ativa. > [card] [Visão geral do Connect](/guias/fast-connect/visao-geral) > > Conta master, subcontas e chaves. # Consultar subconta Source: https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta GET /v1/submerchants/{id} Devolve os dados cadastrais, o status de credenciamento e as métricas de uma subconta da sua conta master. Esta rota mostra a situação atual de uma subconta (SubMerchant) específica: dados da empresa, status no credenciamento, datas de aprovação ou inativação e métricas de volume e split. É a forma de confirmar, a qualquer momento, se um vendedor já pode transacionar. ## Quando usar | Situação | Como usar esta rota | | - | - | | Saber se a subconta já foi aprovada | Confira se `status` é `active` | | Confirmar um aviso de status recebido | Consulte depois de receber a notificação e decida pelo `status` da resposta | | Mostrar ao vendedor o volume processado | Use o bloco `metrics` | | Exibir os dados cadastrais no seu sistema | Use os campos da empresa | | Ver várias subcontas de uma vez | Use [Listar subcontas](/referencia/fast-connect/listar-subcontas) | ## Antes de chamar * Tenha o `id` da subconta, devolvido em [Criar subconta](/referencia/fast-connect/criar-subconta) ou em [Listar subcontas](/referencia/fast-connect/listar-subcontas). * Autentique com a chave secreta (`sk_`) da **conta master** à qual a subconta está ligada ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). ## Parâmetros de caminho **id** `string` *required* Identificador único da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. ## Respostas **id** `string` Identificador único da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. **tradeName** `string` Nome fantasia. Ex.: `Loja Exemplo`. **legalName** `string` Razão social. Ex.: `LOJA EXEMPLO LTDA`. **companyTaxId** `string` CNPJ, só com dígitos. Ex.: `11222333000181`. **averageMonthlyRevenue** `number` Faturamento médio mensal informado no cadastro. O contrato descreve o campo como "decimal as string", mas o tipo declarado é `number`. Ex.: `5000`. **averageOrderValue** `number` Ticket médio informado no cadastro. O contrato descreve o campo como "decimal as string", mas o tipo declarado é `number`. Ex.: `100`. **productType** `string` Tipo de produto vendido: `digital`, `physical` ou `both`. **website** `string` Site da subconta (formato `uri`). Ex.: `https://loja.exemplo.com.br`. **gatewayId** `string` Identificador do gateway ligado à subconta. Ex.: `36O08tjxJCxtEFApVPyWbryktP3`. **approvedAt** `string | null` Data e hora da aprovação (formato `date-time`). Ex.: `2026-10-21T14:02:51.762Z`. **inactivatedAt** `string | null` Data e hora da inativação (formato `date-time`). Ex.: `null`. **status** `string` Status atual: `active`, `pending`, `pre_approved`, `correcting`, `inactive`, `rejected` ou `blocked`. **metrics** `object` Métricas agregadas da subconta. **propriedades** **totalVolume** `number` Volume total de cobranças da subconta (soma dos valores), em reais. Ex.: `15000` (R\$ 15.000,00). **splitBalance** `number` Total recebido pela subconta via split, em reais. Ex.: `450` (R\$ 450,00). **splitRate** `number` Percentual médio de split aplicado à subconta. Ex.: `3`. **contactEmail** `string` E-mail de contato (formato `email`). Ex.: `contato@lojaexemplo.com.br`. **productDescription** `string` Descrição dos produtos ou serviços. Ex.: `Roupas e acessórios femininos`. **softDescriptor** `string | null` Nome que aparece na fatura do cartão do cliente. Ex.: `null`. **createdAt** `string` Data e hora de criação (formato `date-time`). Ex.: `2026-10-20T18:45:52.988Z`. **totalSales** `number` Total de vendas da subconta. Ex.: `0`. > [!NOTE] > > O contrato desta rota não informa quais campos são sempre presentes. Trate qualquer campo como possivelmente ausente. ### O que fazer em cada status | Status | Próximo passo | | - | - | | `pending` | Cadastro em análise. Confira se todos os documentos foram enviados | | `correcting` | A Finvia pediu correção de dados ou documentos. Corrija no painel, na gestão de subcontas. Depois do reenvio, a subconta volta para a análise | | `pre_approved` | Documentos obrigatórios conferidos. A subconta está sendo credenciada nas adquirentes e aguarda a aprovação final | | `active` | Aprovada. Busque as [chaves de API](/referencia/fast-connect/chaves-de-api) da subconta e libere as vendas | | `rejected` | Reprovada. Veja os motivos comuns em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento) | | `blocked` | Bloqueada | | `inactive` | Inativada | O motivo de uma recusa ou de um pedido de correção chega no campo `rejectionReason` do aviso de status, descrito em [Webhooks de conta](/guias/webhooks/conta). Esta rota não devolve esse campo. | HTTP | Significado | Corpo | | - | - | - | | `200` | Subconta encontrada | Objeto da subconta | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` | > [!NOTE] > > **Para o negócio:** antes de liberar um vendedor para vender na sua plataforma, confira se o status é `active`. Uma subconta que ainda não foi aprovada não está apta a transacionar. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` | Chave ausente, inválida ou mal codificada no Basic | Codifique `chave:` em Base64 (com os dois-pontos no fim) | | `403` `Fast Connect not enabled.` | Connect não habilitado na conta master | Peça a habilitação à Finvia | | Status parado em `correcting` | Correções pedidas e ainda não feitas | Corrija os dados ou reenvie os documentos pedidos | ```http REST (JSON) theme={null} GET /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const id = '36OO3bcGjhPjjF3tzrqOGcmQuKo'; const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants/${id}`, { headers: { Authorization: `Basic ${credentials}` }, }); const submerchant = await response.json(); if (submerchant.status === 'active') { // liberar vendas e buscar as chaves da subconta } ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "tradeName": "Loja Exemplo", "legalName": "LOJA EXEMPLO LTDA", "companyTaxId": "11222333000181", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "physical", "website": "https://loja.exemplo.com.br", "gatewayId": "36O08tjxJCxtEFApVPyWbryktP3", "approvedAt": "2026-10-21T14:02:51.762Z", "inactivatedAt": null, "status": "active", "metrics": { "totalVolume": 15000, "splitBalance": 450, "splitRate": 3 }, "contactEmail": "contato@lojaexemplo.com.br", "productDescription": "Roupas e acessórios femininos", "softDescriptor": null, "createdAt": "2026-10-20T18:45:52.988Z", "totalSales": 0 } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Fast Connect not enabled." } ``` ## Veja também > [card] [Listar subcontas](/referencia/fast-connect/listar-subcontas) > > Todas as subcontas, com filtros. > [card] [Chaves de API da subconta](/referencia/fast-connect/chaves-de-api) > > Chaves para cobrar em nome do vendedor. > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Ciclo de credenciamento. > [card] [Webhooks de conta](/guias/webhooks/conta) > > Avisos de mudança de status. # Criar saque da subconta Source: https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque POST /v1/submerchants/{merchantId}/payout-requests A conta master solicita um saque (payout) do saldo de uma subconta, pago por Pix na chave CNPJ da própria subconta. Esta rota cria uma solicitação de saque (payout) para uma subconta (SubMerchant) do [Connect](/guias/fast-connect/visao-geral). Quem chama é a conta master, com a própria chave secreta. O valor sai do saldo disponível da subconta e é enviado por **Pix**, em reais, para a **chave Pix CNPJ da subconta**. A solicitação nasce `pending` e sempre passa por aprovação manual da operação Finvia. ## Quando usar | Situação | Como usar esta rota | | - | - | | O vendedor pede para sacar o saldo pelo seu sistema | Informe o `merchantId` da subconta e o `amount` em reais | | Repasse periódico para os vendedores | Chame a rota para cada subconta no ciclo que a sua operação definir | | Saque do saldo da própria conta master | Passe o `id` da própria master no caminho, ou use [Solicitar saque](/referencia/saques/criar) | | Acompanhar um saque já pedido | Use [Listar saques](/referencia/saques/listar) | ## Antes de chamar * Use a chave secreta (`sk_`) **da conta master** em Basic. A conta master precisa ter o Connect habilitado pela Finvia; sem isso, a resposta é `403` `Fast Connect not enabled.`. * A chave age com as permissões do usuário que a gerou. Uma chave de usuário com perfil **Desenvolvedor** recebe `403` `Acesso negado`. Use a chave padrão da conta (do proprietário) ou uma gerada por Owner ou Manager. * Não existe saque no Modo Teste: com a chave de teste (`sk_test_`), a resposta é `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. * A subconta precisa estar **ativa** (`active`), com **CNPJ** cadastrado, saques habilitados e **taxa de saque** configurada. * O CNPJ da subconta precisa estar cadastrado como **chave Pix** em uma conta bancária da empresa. A API não confere isso na criação do saque. > [!WARNING] > > O valor vai em **reais**: `"amount": 100` significa R\$ 100,00, e `100.50` significa R\$ 100,50. O mínimo é `1` (R\$ 1,00). Enviar `10000` pensando em R\$ 100,00 pede um saque de R\$ 10.000,00. ## Parâmetros de caminho **merchantId** `string` *required* ID da subconta que vai sacar. A conta master também pode informar o próprio `id` para sacar o próprio saldo. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. ## Corpo da requisição **amount** `number` *required* Valor do saque em reais. Aceita casas decimais (ex.: `100.50` = R\$ 100,50). Mínimo: `1` (R\$ 1,00). Ex.: `100`. Não há outros campos. A moeda é sempre `BRL` e o destino é sempre Pix na chave CNPJ da subconta: não é possível informar outra conta de destino. ## Respostas **id** `string` Identificador da solicitação de saque criada. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. Guarde este valor: ele chega no campo `id` dos webhooks de saque e identifica o saque na listagem. | HTTP | Significado | Exemplo de corpo | | - | - | - | | `201` | Solicitação de saque criada | `{"id": "2vorkDcXyvzifL63YX09S9VqcnI"}` | | `400` | Corpo inválido, com `message` em lista | `{"statusCode": 400, "message": ["amount must not be less than 1"], "error": "Bad Request"}` | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Connect não habilitado, chave de teste (`WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`) ou usuário sem permissão de saque (`Acesso negado`) | `{"statusCode": 403, "message": "Fast Connect not enabled."}` | | `404` | Subconta inexistente ou de outra conta master | `{"statusCode": 404, "message": "SubMerchant not found", "error": "Not Found"}` | | `422` | Regra de negócio impediu o saque (mensagens abaixo) | `{"statusCode": 422, "message": "...", "error": "Unprocessable Entity"}` | As mensagens vêm em inglês. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição. ### Validação do valor (`400`) | `amount` enviado | `message` | | - | - | | `0` | `["amount must be a positive number", "amount must not be less than 1"]` | | `0.5` | `["amount must not be less than 1"]` | ### Mensagens do `422` | `message` | Causa | Como resolver | | - | - | - | | `SubMerchant account is not active` | A subconta não está `active` | Confira o status em [Consultar subconta](/referencia/fast-connect/consultar-subconta) | | `SubMerchant is blocked. Withdrawals are not allowed.` | A subconta está bloqueada | Fale com o suporte da Finvia | | `Withdrawals are disabled for this submerchant` | Saques desabilitados para a subconta | Fale com o suporte da Finvia | | `SubMerchant CNPJ not configured` | A subconta não tem CNPJ cadastrado | Fale com o suporte da Finvia para completar o cadastro | | `Insufficient balance. Required: X, Available: Y` | O saldo disponível é menor que `amount` | Consulte o saldo e peça um valor menor | | `Maximum withdrawal amount is X BRL` | O valor passa do limite máximo por saque configurado para a conta | Divida em saques menores, um de cada vez | | `You already have a pending withdrawal request for this currency` | Já existe um saque `pending` dessa conta | Aguarde a decisão do saque anterior | | `Merchant settings are not configured correctly` | Configuração da conta incompleta | Fale com o suporte da Finvia | | `Payout fees not configured` | Taxa de saque não configurada | Peça à Finvia a configuração da taxa de saque | ## Taxa e valor líquido A taxa de saque tem uma parte fixa e uma parte percentual sobre o valor, e é descontada do valor pedido: ```text theme={null} payoutFee = taxa fixa + (amount × taxa percentual / 100) netAmount = amount − payoutFee ``` Com `amount` `100` e taxa de R\$ 1,00, chegam R\$ 99,00 no Pix. Na listagem e nos webhooks de saque, os valores chegam como texto decimal com 8 casas (ex.: `"99.00000000"`). ## Status e acompanhamento **1. Solicitação criada** A resposta `201` traz o `id`. O valor bruto sai do saldo disponível da subconta e o saque fica `pending`. **2. Aprovação ou recusa** A operação Finvia aprova (`approved`) ou recusa (`rejected`). Na aprovação, o Pix do valor líquido é enviado. Na recusa, o valor volta ao saldo disponível. **3. Aviso por webhook** Os eventos `payout.approved` e `payout.rejected` vão para os endpoints de webhook cadastrados na subconta e para os endpoints da master cadastrados com a opção de incluir subcontas. Veja [Webhooks de saque](/guias/webhooks/saque). `approved` significa aprovado e enviado para pagamento. Ele não confirma que o dinheiro já chegou à conta de destino. > [!NOTE] > > O Pix vai para a chave CNPJ da subconta (o mesmo CNPJ do cadastro). A API não consulta se essa chave existe. Se o CNPJ não estiver cadastrado como chave Pix, o Pix não é concluído e o status do saque na API não mostra essa falha. Nesse caso, fale com o suporte da Finvia. **Em validação (V-49):** o suporte está definindo o procedimento quando o Pix do saque falha (prazo e como o saldo volta). Enquanto isso, se o vendedor não receber um saque `approved`, abra um chamado com o `id` do saque. > [!NOTE] > > **Para o negócio:** o vendedor precisa ter o CNPJ da empresa cadastrado como chave Pix antes do primeiro saque. A taxa de saque é descontada do valor pedido. Como todo saque de subconta passa por aprovação manual, combine com os vendedores que o dinheiro não cai na hora do pedido. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Saque 100 vezes maior que o esperado | `amount` enviado em centavos | Envie em reais: `100` = R\$ 100,00 | | `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chamada com chave de teste | Saques só existem em produção | | `403` `Acesso negado` | Chave gerada por usuário com perfil Desenvolvedor | Use a chave padrão da conta master | | `403` `Fast Connect not enabled.` | Connect não habilitado na conta master | Peça a habilitação à Finvia | | `404` `SubMerchant not found` | `merchantId` inexistente ou de outra conta master | Confira o `id` em [Listar subcontas](/referencia/fast-connect/listar-subcontas) | | `422` `You already have a pending withdrawal request for this currency` | Saque anterior ainda pendente | Aguarde a aprovação ou a recusa | | Saque `approved` e o vendedor não recebeu | O CNPJ da subconta não está cadastrado como chave Pix | Fale com o suporte da Finvia | ```http REST (JSON) theme={null} POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "amount": 100 } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "amount": 100 }' ``` ```javascript Node.js theme={null} const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const merchantId = '36OO3bcGjhPjjF3tzrqOGcmQuKo'; const response = await fetch( `https://api-global.fastpaybrasil.com/v1/submerchants/${merchantId}/payout-requests`, { method: 'POST', headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 100 }), // R$ 100,00 }, ); const result = await response.json(); if (response.status === 201) { console.log('Saque criado:', result.id); // guarde para conciliar com payout.approved / payout.rejected } else { console.error(response.status, result.message); } ``` ```python Python theme={null} import os import requests payload = { "amount": 100, } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 100, ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "amount": 100 } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "amount": 100 } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "amount": 100 }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "amount" => 100, }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "id": "2vorkDcXyvzifL63YX09S9VqcnI" } ``` ```json 400 theme={null} { "statusCode": 400, "message": ["amount must be a positive number", "amount must not be less than 1"], "error": "Bad Request" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Fast Connect not enabled." } ``` ```json 404 theme={null} { "statusCode": 404, "message": "SubMerchant not found", "error": "Not Found" } ``` ```json 422 Subconta inativa theme={null} { "statusCode": 422, "message": "SubMerchant account is not active", "error": "Unprocessable Entity" } ``` ```json 422 Taxa não configurada theme={null} { "statusCode": 422, "message": "Payout fees not configured", "error": "Unprocessable Entity" } ``` ## Veja também > [card] [Saques no Connect](/guias/fast-connect/saques) > > Fluxo completo de saque das subcontas. > [card] [Listar saques](/referencia/saques/listar) > > Acompanhe status e valores. > [card] [Webhooks de saque](/guias/webhooks/saque) > > Eventos `payout.approved` e `payout.rejected`. > [card] [Homologação](/homologacao/roteiro) > > Cenário FC-07: saque da subconta. # Criar subconta Source: https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta POST /v1/submerchants Cadastra uma subconta ligada à sua conta master, com dados da empresa, representante legal, sócios e conta bancária. Esta rota cria uma subconta (SubMerchant) da Finvia vinculada à sua conta master (MerchantMaster) no [Connect](/guias/fast-connect/visao-geral). É o primeiro passo para colocar um vendedor, franqueado ou parceiro para receber pagamentos dentro da sua plataforma. A subconta nasce em análise (`pending`) e só pode transacionar depois de aprovada no credenciamento (KYC, a verificação de identidade da empresa e dos sócios). ## Quando usar | Situação | Como usar esta rota | | - | - | | Vendedor novo se cadastra na sua plataforma | Envie os dados da empresa, o representante legal e a conta bancária | | Empresa com mais de um sócio | Envie também `additionalRepresentatives` e guarde os `id` devolvidos em `legalRepresentatives` | | O vendedor vai usar o painel da Finvia | `canAccessDashboard: true` e o objeto `user` | | O vendedor só vai operar pelo seu sistema | `canAccessDashboard: false`, sem `user` | | Consultar uma subconta já criada | Use [Consultar subconta](/referencia/fast-connect/consultar-subconta) | ## Antes de chamar * O módulo Connect precisa estar habilitado pela Finvia na sua conta master. Sem isso, a resposta é `403` `Fast Connect not enabled.`. * Autentique com a chave secreta (`sk_`) da **conta master** ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Pré-valide o cadastro do lojista do seu lado antes de enviar, como pedem as [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). * Tenha em mãos os dados da empresa, do representante legal (e dos demais sócios, se houver) e da conta bancária de recebimento. * Os documentos (cartão CNPJ, contrato social, documento com foto e selfie) **não** vão nesta chamada. Eles são enviados depois, com o `id` devolvido aqui ([Sócios e documentos](/guias/fast-connect/socios-e-documentos)). > [!NOTE] > > **Para o negócio:** na criação, a subconta recebe uma cópia das taxas e configurações vigentes da conta master. Depois disso, as taxas da subconta são independentes: mudar as taxas da master não altera as das subcontas já criadas. As taxas de cada subconta podem ser consultadas em [Taxas e dados da subconta](/referencia/fast-connect/taxas-e-dados). ## Corpo da requisição Campos obrigatórios: `legalName`, `tradeName`, `companyTaxId`, `website`, `averageMonthlyRevenue`, `averageOrderValue`, `productType`, `legalRepresentative`, `contactEmail`, `productDescription`, `address`, `phones`, `bankAccount` e `canAccessDashboard`. ### Dados da empresa **legalName** `string` *required* Razão social. Ex.: `LOJA EXEMPLO LTDA`. **tradeName** `string` *required* Nome fantasia. Ex.: `Loja Exemplo`. **companyTaxId** `string` *required* CNPJ da empresa, com ou sem máscara. Quando `address.country` é `BRA`, precisa ser um CPF ou CNPJ com dígito verificador válido. O valor é gravado só com dígitos. Ex.: `11.222.333/0001-81`. **website** `string` *required* Site da empresa (formato `uri`). Informe a URL onde estão os produtos ou serviços que serão vendidos: ela é conferida no credenciamento. Ex.: `https://loja.exemplo.com.br`. **averageMonthlyRevenue** `number` *required* Expectativa de faturamento médio mensal, em reais. Ex.: `30000`. **averageOrderValue** `number` *required* Ticket médio por pedido, em reais. Ex.: `150`. **productType** `string` *required* Tipo de produto vendido: `digital`, `physical` ou `both`. Ex.: `physical`. **contactEmail** `string` *required* E-mail de contato da empresa. Ex.: `contato@lojaexemplo.com.br`. **productDescription** `string` *required* Descrição curta dos produtos ou serviços. Ex.: `Roupas e acessórios femininos`. **softDescriptor** `string` Nome que aparece na fatura do cartão do cliente. Máximo de 40 caracteres (`maxLength` 40). Ex.: `LOJAEXEMPLO`. **address** `object` *required* Endereço da empresa. O país define as regras dos outros campos (veja a tabela abaixo). **propriedades** **addressLine1** `string` *required* Logradouro e número, separados por vírgula, com o número no fim. Ex.: `Av. Paulista, 1000`. O número é extraído desse formato para o credenciamento nas adquirentes. Sem vírgula e número no fim, ele pode ser enviado como "S/N". **addressLine2** `string` Complemento (apartamento, sala, bloco, andar). Opcional; se omitido, é gravado vazio. Ex.: `Sala 12`. **referencePoint** `string` Ponto de referência do endereço. Opcional, até 255 caracteres. Ex.: `Próximo à estação Trianon-Masp`. **neighborhood** `string` *required* Bairro. Obrigatório quando o país é `BRA`. Ex.: `Bela Vista`. **city** `string` *required* Cidade. Ex.: `São Paulo`. **state** `string` *required* Estado. Quando o país é `BRA`, precisa ser uma UF válida. Ex.: `SP`. **country** `string` *required* País, em ISO 3166-1 alpha-3 (três letras maiúsculas, padrão `^[A-Z]{3}$`). Ex.: `BRA`. O formato alpha-2 (`BR`) é recusado com `400`. **postalCode** `string` *required* CEP. Quando o país é `BRA`, precisa ter 8 dígitos. Ex.: `01310100`. **phones** `object[]` *required* Telefones da empresa. **propriedades** **type** `string` *required* Tipo do telefone. Ex.: `mobile`. **number** `string` *required* Número do telefone. Ex.: `+5511987654321`. #### Regras que dependem do país | Campo | Quando o país do endereço é `BRA` | | - | - | | `companyTaxId` | CPF ou CNPJ com dígito verificador válido | | `address.state` | UF válida (ex.: `SP`) | | `address.postalCode` | CEP com 8 dígitos | | `address.neighborhood` | Obrigatório | | `idNumber` do representante e dos sócios | CPF válido quando `issuingCountry` é `BRA` ou não é enviado | Todos os campos de país da subconta usam ISO 3166-1 alpha-3: `address.country`, `address.country` do representante e dos sócios, e `issuingCountry`. A validação não diferencia maiúsculas de minúsculas, mas o valor é gravado como foi enviado: envie sempre em maiúsculas. ### Representante legal e sócios **legalRepresentative** `object` *required* Representante legal da empresa. É sempre o representante principal da subconta (`isPrimary: true`), e os documentos de pessoa enviados sem indicar um sócio ficam ligados a ele. **propriedades** **fullName** `string` *required* Nome completo. Ex.: `Ana Lima`. **dateOfBirth** `string` *required* Data de nascimento (formato `date`). Ex.: `1988-04-12`. **nationality** `string` *required* Nacionalidade, em texto livre (não é código de país). Ex.: `Brasileira`. **idNumber** `string` *required* Número do documento. Precisa ser um CPF válido quando `issuingCountry` é `BRA` ou não é enviado. Ex.: `52998224725`. **idType** `string` Tipo do documento de identificação. Ex.: `cpf`. **issuingCountry** `string` País emissor do documento, em ISO 3166-1 alpha-3. Opcional. Ex.: `BRA`. **email** `string` *required* E-mail. Ex.: `ana.lima@email.com`. **motherName** `string` *required* Nome da mãe. Ex.: `Maria Lima`. **gender** `string` *required* Gênero: `M` ou `F`. **address** `object` Endereço próprio do representante. Opcional: sem ele, o representante usa o endereço da empresa. Quando enviado, `country` é obrigatório. **propriedades** **addressLine1** `string` *required* Logradouro e número, separados por vírgula. Ex.: `Rua Augusta, 500`. **addressLine2** `string` Complemento. Opcional. Ex.: `Apto 31`. **neighborhood** `string` *required* Bairro. Ex.: `Consolação`. **city** `string` *required* Cidade. Ex.: `São Paulo`. **state** `string` *required* Estado. Ex.: `SP`. **country** `string` *required* País, em ISO 3166-1 alpha-3. Ex.: `BRA`. **postalCode** `string` *required* CEP. Ex.: `01305000`. **phones** `object[]` *required* Telefones do representante. **propriedades** **type** `string` *required* Tipo do telefone. Ex.: `mobile`. **number** `string` *required* Número do telefone. Ex.: `+5511987654321`. **additionalRepresentatives** `object[]` Sócios adicionais da empresa (opcional). Cada item tem o **mesmo formato** do `legalRepresentative`, com as mesmas regras de país e de CPF. O `legalRepresentative` continua obrigatório e é sempre o representante legal; os adicionais são cadastrados como sócios. Os documentos dos sócios não vão neste corpo: depois da criação, use os `id` devolvidos em `legalRepresentatives` para enviar os documentos de cada sócio com [token de upload](/referencia/fast-connect/criar-token-upload). > [!NOTE] > > O campo `referencePoint` só é gravado no endereço da empresa. No endereço próprio do representante ou de um sócio ele é aceito, mas descartado. ### Conta bancária **bankAccount** `object` *required* Conta bancária da subconta. Todos os campos são obrigatórios, exceto `routingNumber`. **propriedades** **bankCode** `string` *required* Código do banco. Ex.: `001`. **agencyCode** `string` *required* Agência. Ex.: `1234`. **accountNumber** `string` *required* Número da conta. Ex.: `567890`. **accountDigit** `string` *required* Dígito da conta. Ex.: `0`. **accountType** `string` *required* Tipo da conta: `checking` (corrente) ou `savings` (poupança). **bankName** `string` *required* Nome do banco. Ex.: `Banco do Brasil`. **recipientName** `string` *required* Nome do titular da conta. Ex.: `LOJA EXEMPLO LTDA`. **recipientDocument** `string` *required* CPF ou CNPJ do titular da conta, validado pelos dígitos verificadores. Ex.: `11222333000181`. **routingNumber** `string` Routing number, para contas dos Estados Unidos. Opcional. > [!WARNING] > > `companyTaxId`, `idNumber` (do representante e dos sócios) e `bankAccount.recipientDocument` são validados pelos dígitos verificadores. Os números dos exemplos desta página são válidos só para teste de formato: na sua integração, envie os documentos reais do lojista. ### Acesso ao painel e notificações **canAccessDashboard** `boolean` *required* Define se a subconta pode acessar o painel da Finvia. Ex.: `true`. **user** `object` Usuário que vai acessar o painel. **Obrigatório quando `canAccessDashboard` é `true`.** Quando o objeto é enviado, os três campos são obrigatórios. Se o e-mail já tiver usuário cadastrado, a resposta é `400` `Email already registered`. **propriedades** **fullName** `string` *required* Nome do usuário. Ex.: `Ana Lima`. **email** `string` *required* E-mail do usuário. Ex.: `ana.lima@email.com`. **phone** `string` *required* Telefone no formato internacional estrito (E.164). Ex.: `+5511987654321`. **postbackUrl** `string` URL (formato `uri`) para receber os avisos de mudança de status da subconta. Opcional. Ex.: `https://meusite.com.br/webhooks/finvia/conta`. A URL fica salva nas configurações da subconta. Para alterá-la depois, fale com o suporte. Sem `postbackUrl`, a subconta usa a URL de aviso de status da conta master, se a master tiver uma. Esta URL não recebe eventos de cobrança. O aviso vem sem envelope, em camelCase, com `merchantId`, `status`, `date` e, quando o status é `rejected` ou `correcting`, `rejectionReason`. Veja [Webhooks de conta](/guias/webhooks/conta). ## Respostas A resposta `201` traz só o `id` da subconta e os representantes criados. Para ver o cadastro completo, use [Consultar subconta](/referencia/fast-connect/consultar-subconta). **id** `string` *required* Identificador da subconta criada. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. Guarde este valor: ele é usado para enviar documentos, consultar a subconta, obter as chaves de API e pedir saques. **legalRepresentatives** `object[]` Representantes criados: o **representante legal primeiro** (`isPrimary: true`) e depois os sócios adicionais, na ordem enviada. Use os `id` dos itens com `isPrimary: false` para enviar os documentos de cada sócio. **propriedades** **id** `string` Identificador do representante ou sócio. Ex.: `2vorkEaaaBbbCccDddEeeFffGgg`. **fullName** `string` Nome completo. Ex.: `Ana Lima`. **isPrimary** `boolean` `true` apenas no representante legal da empresa. | HTTP | Significado | Corpo | | - | - | - | | `201` | Subconta criada | `id`, `legalRepresentatives` | | `400` | Corpo inválido, com `message` em lista | `{"statusCode": 400, "message": ["bankAccount.bankCode should not be empty"], "error": "Bad Request"}` | | `400` | E-mail do usuário do painel já cadastrado (com `canAccessDashboard: true`) | `{"statusCode": 400, "message": "Email already registered", "error": "Bad Request"}` | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` | | `409` | CNPJ já cadastrado em outra subconta da mesma master (em qualquer status) ou igual ao CNPJ da própria master | `{"statusCode": 409, "message": "Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.", "error": "Conflict"}` | As mensagens misturam português e inglês. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição. > [!TIP] > > A criação deu certo quando a resposta é `201` com um `id`. A subconta começa em análise (`pending`) e só pode transacionar quando chegar a `active`. ## Depois de criar **1. Envie os documentos** Use [Enviar documentos](/referencia/fast-connect/enviar-documentos) para os documentos da empresa e do representante legal. Para cada sócio adicional, gere um [token de upload](/referencia/fast-connect/criar-token-upload) com o `id` dele. A lista de documentos exigidos está em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). **2. Acompanhe a análise** Receba os avisos de status no `postbackUrl` e consulte a subconta com [Consultar subconta](/referencia/fast-connect/consultar-subconta). Se o status for `correcting`, corrija os dados ou documentos pedidos. **3. Obtenha as chaves** Com a subconta `active`, busque as chaves dela em [Chaves de API da subconta](/referencia/fast-connect/chaves-de-api) para criar cobranças em nome do vendedor. ## Exemplos por caso de uso > [tab] Sócio único, sem painel > > Vendedor que opera só pela sua plataforma. O representante usa o endereço da empresa. > > ```json theme={null} > { > "legalName": "LOJA EXEMPLO LTDA", > "tradeName": "Loja Exemplo", > "companyTaxId": "11.222.333/0001-81", > "website": "https://loja.exemplo.com.br", > "averageMonthlyRevenue": 30000, > "averageOrderValue": 150, > "productType": "physical", > "contactEmail": "contato@lojaexemplo.com.br", > "productDescription": "Roupas e acessórios femininos", > "softDescriptor": "LOJAEXEMPLO", > "address": { > "addressLine1": "Av. Paulista, 1000", > "addressLine2": "Sala 12", > "referencePoint": "Próximo à estação Trianon-Masp", > "neighborhood": "Bela Vista", > "city": "São Paulo", > "state": "SP", > "country": "BRA", > "postalCode": "01310100" > }, > "phones": [{ "type": "mobile", "number": "+5511987654321" }], > "legalRepresentative": { > "fullName": "Ana Lima", > "dateOfBirth": "1988-04-12", > "nationality": "Brasileira", > "idNumber": "52998224725", > "idType": "cpf", > "issuingCountry": "BRA", > "email": "ana.lima@email.com", > "motherName": "Maria Lima", > "gender": "F", > "phones": [{ "type": "mobile", "number": "+5511987654321" }] > }, > "bankAccount": { > "bankCode": "001", > "agencyCode": "1234", > "accountNumber": "567890", > "accountDigit": "0", > "accountType": "checking", > "bankName": "Banco do Brasil", > "recipientName": "LOJA EXEMPLO LTDA", > "recipientDocument": "11222333000181" > }, > "canAccessDashboard": false, > "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta" > } > ``` > [tab] Dois sócios, com painel > > Empresa com um sócio adicional, que tem endereço próprio. O vendedor também terá acesso ao painel da Finvia. > > ```json theme={null} > { > "legalName": "LOJA EXEMPLO LTDA", > "tradeName": "Loja Exemplo", > "companyTaxId": "11222333000181", > "website": "https://loja.exemplo.com.br", > "averageMonthlyRevenue": 12000, > "averageOrderValue": 100, > "productType": "both", > "contactEmail": "contato@lojaexemplo.com.br", > "productDescription": "Peças de cerâmica e aulas online", > "address": { > "addressLine1": "Av. Paulista, 1000", > "neighborhood": "Bela Vista", > "city": "São Paulo", > "state": "SP", > "country": "BRA", > "postalCode": "01310100" > }, > "phones": [{ "type": "mobile", "number": "+5511987654321" }], > "legalRepresentative": { > "fullName": "Ana Lima", > "dateOfBirth": "1988-04-12", > "nationality": "Brasileira", > "idNumber": "52998224725", > "email": "ana.lima@email.com", > "motherName": "Maria Lima", > "gender": "F", > "phones": [{ "type": "mobile", "number": "+5511987654321" }] > }, > "additionalRepresentatives": [ > { > "fullName": "Joao Silva", > "dateOfBirth": "1985-05-10", > "nationality": "Brasileira", > "idNumber": "11144477735", > "idType": "cpf", > "issuingCountry": "BRA", > "email": "joao.silva@email.com", > "motherName": "Joana Silva", > "gender": "M", > "address": { > "addressLine1": "Rua Augusta, 500", > "addressLine2": "Apto 31", > "neighborhood": "Consolação", > "city": "São Paulo", > "state": "SP", > "country": "BRA", > "postalCode": "01305000" > }, > "phones": [{ "type": "mobile", "number": "+5511987654321" }] > } > ], > "bankAccount": { > "bankCode": "001", > "agencyCode": "1234", > "accountNumber": "567890", > "accountDigit": "0", > "accountType": "checking", > "bankName": "Banco do Brasil", > "recipientName": "LOJA EXEMPLO LTDA", > "recipientDocument": "11222333000181" > }, > "canAccessDashboard": true, > "user": { > "fullName": "Ana Lima", > "email": "ana.lima@email.com", > "phone": "+5511987654321" > } > } > ``` > > Na resposta, o item com `isPrimary: false` é o sócio Joao Silva. Use o `id` dele ao gerar o token de upload dos documentos pessoais dele. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` `address.country must be a valid ISO31661 Alpha3 code` | País enviado em alpha-2 (`BR`) | Envie `BRA` | | `400` no `companyTaxId` ou no `idNumber` | CNPJ ou CPF com dígito verificador inválido, com país `BRA` | Confira os documentos do lojista e dos sócios | | `400` no CEP, na UF ou no bairro | Com país `BRA`, o CEP precisa ter 8 dígitos, a UF precisa ser válida e o bairro é obrigatório | Corrija o endereço | | `400` com `canAccessDashboard: true` | Objeto `user` ausente ou incompleto, ou `user.phone` fora do E.164 | Envie `user` com `fullName`, `email` e `phone` (ex.: `+5511987654321`) | | `400` `Email already registered` | Já existe usuário do painel com esse e-mail | Use outro e-mail em `user.email` | | `409` com a mensagem de CNPJ já cadastrado | O CNPJ já existe em outra subconta sua, em qualquer status, ou é o CNPJ da master | Consulte a subconta existente em [Listar subcontas](/referencia/fast-connect/listar-subcontas) com `companyTaxId` | | Número do endereço chega como "S/N" na adquirente | `addressLine1` sem vírgula e número no fim | Envie no formato `Av. Paulista, 1000` | | Documentos do sócio ficaram no representante legal | Upload feito sem indicar o sócio | Use o fluxo com token informando o `legalRepresentativeId` do sócio | ```http REST (JSON) theme={null} POST /v1/submerchants HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "legalName": "LOJA EXEMPLO LTDA", "tradeName": "Loja Exemplo", "companyTaxId": "11.222.333/0001-81", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "physical", "contactEmail": "contato@lojaexemplo.com.br", "productDescription": "Roupas e acessórios femininos", "softDescriptor": "LOJAEXEMPLO", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "dateOfBirth": "1988-04-12", "nationality": "Brasileira", "idNumber": "52998224725", "issuingCountry": "BRA", "email": "ana.lima@email.com", "motherName": "Maria Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "additionalRepresentatives": [ { "fullName": "Joao Silva", "dateOfBirth": "1985-05-10", "nationality": "Brasileira", "idNumber": "11144477735", "issuingCountry": "BRA", "email": "joao.silva@email.com", "motherName": "Joana Silva", "gender": "M", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] } ], "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "LOJA EXEMPLO LTDA", "recipientDocument": "11222333000181" }, "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana.lima@email.com", "phone": "+5511987654321" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "legalName": "LOJA EXEMPLO LTDA", "tradeName": "Loja Exemplo", "companyTaxId": "11.222.333/0001-81", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "physical", "contactEmail": "contato@lojaexemplo.com.br", "productDescription": "Roupas e acessórios femininos", "softDescriptor": "LOJAEXEMPLO", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [{ "type": "mobile", "number": "+5511987654321" }], "legalRepresentative": { "fullName": "Ana Lima", "dateOfBirth": "1988-04-12", "nationality": "Brasileira", "idNumber": "52998224725", "issuingCountry": "BRA", "email": "ana.lima@email.com", "motherName": "Maria Lima", "gender": "F", "phones": [{ "type": "mobile", "number": "+5511987654321" }] }, "additionalRepresentatives": [ { "fullName": "Joao Silva", "dateOfBirth": "1985-05-10", "nationality": "Brasileira", "idNumber": "11144477735", "issuingCountry": "BRA", "email": "joao.silva@email.com", "motherName": "Joana Silva", "gender": "M", "phones": [{ "type": "mobile", "number": "+5511987654321" }] } ], "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "LOJA EXEMPLO LTDA", "recipientDocument": "11222333000181" }, "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana.lima@email.com", "phone": "+5511987654321" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta" }' ``` ```javascript Node.js theme={null} const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/submerchants', { method: 'POST', headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ legalName: 'LOJA EXEMPLO LTDA', tradeName: 'Loja Exemplo', companyTaxId: '11222333000181', website: 'https://loja.exemplo.com.br', averageMonthlyRevenue: 30000, // R$ 30.000,00 por mês averageOrderValue: 150, // R$ 150,00 por pedido productType: 'physical', contactEmail: 'contato@lojaexemplo.com.br', productDescription: 'Roupas e acessórios femininos', address: { addressLine1: 'Av. Paulista, 1000', neighborhood: 'Bela Vista', city: 'São Paulo', state: 'SP', country: 'BRA', postalCode: '01310100', }, phones: [{ type: 'mobile', number: '+5511987654321' }], legalRepresentative: { fullName: 'Ana Lima', dateOfBirth: '1988-04-12', nationality: 'Brasileira', idNumber: '52998224725', email: 'ana.lima@email.com', motherName: 'Maria Lima', gender: 'F', phones: [{ type: 'mobile', number: '+5511987654321' }], }, bankAccount: { bankCode: '001', agencyCode: '1234', accountNumber: '567890', accountDigit: '0', accountType: 'checking', bankName: 'Banco do Brasil', recipientName: 'LOJA EXEMPLO LTDA', recipientDocument: '11222333000181', }, canAccessDashboard: false, }), }); const result = await response.json(); if (response.status === 201) { // Guarde result.id e os ids de result.legalRepresentatives console.log(result.id, result.legalRepresentatives); } else if (response.status === 409) { // CNPJ já cadastrado: procure a subconta existente em vez de criar outra } else { console.error(response.status, result.message); } ``` ```python Python theme={null} import os import requests payload = { "legalName": "LOJA EXEMPLO LTDA", "tradeName": "Loja Exemplo", "companyTaxId": "11.222.333/0001-81", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "physical", "contactEmail": "contato@lojaexemplo.com.br", "productDescription": "Roupas e acessórios femininos", "softDescriptor": "LOJAEXEMPLO", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100", }, "phones": [ { "type": "mobile", "number": "+5511987654321", }, ], "legalRepresentative": { "fullName": "Ana Lima", "dateOfBirth": "1988-04-12", "nationality": "Brasileira", "idNumber": "52998224725", "issuingCountry": "BRA", "email": "ana.lima@email.com", "motherName": "Maria Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321", }, ], }, "additionalRepresentatives": [ { "fullName": "Joao Silva", "dateOfBirth": "1985-05-10", "nationality": "Brasileira", "idNumber": "11144477735", "issuingCountry": "BRA", "email": "joao.silva@email.com", "motherName": "Joana Silva", "gender": "M", "phones": [ { "type": "mobile", "number": "+5511987654321", }, ], }, ], "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "LOJA EXEMPLO LTDA", "recipientDocument": "11222333000181", }, "canAccessDashboard": True, "user": { "fullName": "Ana Lima", "email": "ana.lima@email.com", "phone": "+5511987654321", }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/submerchants", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'LOJA EXEMPLO LTDA', 'tradeName' => 'Loja Exemplo', 'companyTaxId' => '11.222.333/0001-81', 'website' => 'https://loja.exemplo.com.br', 'averageMonthlyRevenue' => 30000, 'averageOrderValue' => 150, 'productType' => 'physical', 'contactEmail' => 'contato@lojaexemplo.com.br', 'productDescription' => 'Roupas e acessórios femininos', 'softDescriptor' => 'LOJAEXEMPLO', 'address' => [ 'addressLine1' => 'Av. Paulista, 1000', 'addressLine2' => 'Sala 12', 'neighborhood' => 'Bela Vista', 'city' => 'São Paulo', 'state' => 'SP', 'country' => 'BRA', 'postalCode' => '01310100', ], 'phones' => [ [ 'type' => 'mobile', 'number' => '+5511987654321', ], ], 'legalRepresentative' => [ 'fullName' => 'Ana Lima', 'dateOfBirth' => '1988-04-12', 'nationality' => 'Brasileira', 'idNumber' => '52998224725', 'issuingCountry' => 'BRA', 'email' => 'ana.lima@email.com', 'motherName' => 'Maria Lima', 'gender' => 'F', 'phones' => [ [ 'type' => 'mobile', 'number' => '+5511987654321', ], ], ], 'additionalRepresentatives' => [ [ 'fullName' => 'Joao Silva', 'dateOfBirth' => '1985-05-10', 'nationality' => 'Brasileira', 'idNumber' => '11144477735', 'issuingCountry' => 'BRA', 'email' => 'joao.silva@email.com', 'motherName' => 'Joana Silva', 'gender' => 'M', 'phones' => [ [ 'type' => 'mobile', 'number' => '+5511987654321', ], ], ], ], 'bankAccount' => [ 'bankCode' => '001', 'agencyCode' => '1234', 'accountNumber' => '567890', 'accountDigit' => '0', 'accountType' => 'checking', 'bankName' => 'Banco do Brasil', 'recipientName' => 'LOJA EXEMPLO LTDA', 'recipientDocument' => '11222333000181', ], 'canAccessDashboard' => true, 'user' => [ 'fullName' => 'Ana Lima', 'email' => 'ana.lima@email.com', 'phone' => '+5511987654321', ], 'postbackUrl' => 'https://meusite.com.br/webhooks/finvia/conta', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "legalName": "LOJA EXEMPLO LTDA", "tradeName": "Loja Exemplo", "companyTaxId": "11.222.333/0001-81", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "physical", "contactEmail": "contato@lojaexemplo.com.br", "productDescription": "Roupas e acessórios femininos", "softDescriptor": "LOJAEXEMPLO", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "dateOfBirth": "1988-04-12", "nationality": "Brasileira", "idNumber": "52998224725", "issuingCountry": "BRA", "email": "ana.lima@email.com", "motherName": "Maria Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "additionalRepresentatives": [ { "fullName": "Joao Silva", "dateOfBirth": "1985-05-10", "nationality": "Brasileira", "idNumber": "11144477735", "issuingCountry": "BRA", "email": "joao.silva@email.com", "motherName": "Joana Silva", "gender": "M", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] } ], "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "LOJA EXEMPLO LTDA", "recipientDocument": "11222333000181" }, "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana.lima@email.com", "phone": "+5511987654321" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "legalName": "LOJA EXEMPLO LTDA", "tradeName": "Loja Exemplo", "companyTaxId": "11.222.333/0001-81", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "physical", "contactEmail": "contato@lojaexemplo.com.br", "productDescription": "Roupas e acessórios femininos", "softDescriptor": "LOJAEXEMPLO", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "dateOfBirth": "1988-04-12", "nationality": "Brasileira", "idNumber": "52998224725", "issuingCountry": "BRA", "email": "ana.lima@email.com", "motherName": "Maria Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "additionalRepresentatives": [ { "fullName": "Joao Silva", "dateOfBirth": "1985-05-10", "nationality": "Brasileira", "idNumber": "11144477735", "issuingCountry": "BRA", "email": "joao.silva@email.com", "motherName": "Joana Silva", "gender": "M", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] } ], "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "LOJA EXEMPLO LTDA", "recipientDocument": "11222333000181" }, "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana.lima@email.com", "phone": "+5511987654321" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "legalName": "LOJA EXEMPLO LTDA", "tradeName": "Loja Exemplo", "companyTaxId": "11.222.333/0001-81", "website": "https://loja.exemplo.com.br", "averageMonthlyRevenue": 30000, "averageOrderValue": 150, "productType": "physical", "contactEmail": "contato@lojaexemplo.com.br", "productDescription": "Roupas e acessórios femininos", "softDescriptor": "LOJAEXEMPLO", "address": { "addressLine1": "Av. Paulista, 1000", "addressLine2": "Sala 12", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BRA", "postalCode": "01310100" }, "phones": [ { "type": "mobile", "number": "+5511987654321" } ], "legalRepresentative": { "fullName": "Ana Lima", "dateOfBirth": "1988-04-12", "nationality": "Brasileira", "idNumber": "52998224725", "issuingCountry": "BRA", "email": "ana.lima@email.com", "motherName": "Maria Lima", "gender": "F", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] }, "additionalRepresentatives": [ { "fullName": "Joao Silva", "dateOfBirth": "1985-05-10", "nationality": "Brasileira", "idNumber": "11144477735", "issuingCountry": "BRA", "email": "joao.silva@email.com", "motherName": "Joana Silva", "gender": "M", "phones": [ { "type": "mobile", "number": "+5511987654321" } ] } ], "bankAccount": { "bankCode": "001", "agencyCode": "1234", "accountNumber": "567890", "accountDigit": "0", "accountType": "checking", "bankName": "Banco do Brasil", "recipientName": "LOJA EXEMPLO LTDA", "recipientDocument": "11222333000181" }, "canAccessDashboard": true, "user": { "fullName": "Ana Lima", "email": "ana.lima@email.com", "phone": "+5511987654321" }, "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "legalName" => "LOJA EXEMPLO LTDA", "tradeName" => "Loja Exemplo", "companyTaxId" => "11.222.333/0001-81", "website" => "https://loja.exemplo.com.br", "averageMonthlyRevenue" => 30000, "averageOrderValue" => 150, "productType" => "physical", "contactEmail" => "contato@lojaexemplo.com.br", "productDescription" => "Roupas e acessórios femininos", "softDescriptor" => "LOJAEXEMPLO", "address" => { "addressLine1" => "Av. Paulista, 1000", "addressLine2" => "Sala 12", "neighborhood" => "Bela Vista", "city" => "São Paulo", "state" => "SP", "country" => "BRA", "postalCode" => "01310100", }, "phones" => [ { "type" => "mobile", "number" => "+5511987654321", }, ], "legalRepresentative" => { "fullName" => "Ana Lima", "dateOfBirth" => "1988-04-12", "nationality" => "Brasileira", "idNumber" => "52998224725", "issuingCountry" => "BRA", "email" => "ana.lima@email.com", "motherName" => "Maria Lima", "gender" => "F", "phones" => [ { "type" => "mobile", "number" => "+5511987654321", }, ], }, "additionalRepresentatives" => [ { "fullName" => "Joao Silva", "dateOfBirth" => "1985-05-10", "nationality" => "Brasileira", "idNumber" => "11144477735", "issuingCountry" => "BRA", "email" => "joao.silva@email.com", "motherName" => "Joana Silva", "gender" => "M", "phones" => [ { "type" => "mobile", "number" => "+5511987654321", }, ], }, ], "bankAccount" => { "bankCode" => "001", "agencyCode" => "1234", "accountNumber" => "567890", "accountDigit" => "0", "accountType" => "checking", "bankName" => "Banco do Brasil", "recipientName" => "LOJA EXEMPLO LTDA", "recipientDocument" => "11222333000181", }, "canAccessDashboard" => true, "user" => { "fullName" => "Ana Lima", "email" => "ana.lima@email.com", "phone" => "+5511987654321", }, "postbackUrl" => "https://meusite.com.br/webhooks/finvia/conta", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "legalRepresentatives": [ { "id": "2vorkEaaaBbbCccDddEeeFffGgg", "fullName": "Ana Lima", "isPrimary": true }, { "id": "2vorkEbbbCccDddEeeFffGggHhh", "fullName": "Joao Silva", "isPrimary": false } ] } ``` ```json 400 theme={null} { "statusCode": 400, "message": ["address.country must be a valid ISO31661 Alpha3 code"], "error": "Bad Request" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Fast Connect not enabled." } ``` ```json 409 theme={null} { "statusCode": 409, "message": "Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.", "error": "Conflict" } ``` ## Veja também > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Cadastro e credenciamento passo a passo. > [card] [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento) > > Documentos exigidos, motivos de recusa e MCCs não aceitos. > [card] [Sócios e documentos](/guias/fast-connect/socios-e-documentos) > > Documentos de cada sócio com token de upload. > [card] [Webhooks de conta](/guias/webhooks/conta) > > Avisos de mudança de status. # Criar token de upload Source: https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload POST /v1/submerchants/{merchantId}/document/upload-token Emite um token de curta duração para enviar documentos da subconta sem expor a chave secreta, com vínculo opcional a um sócio. Esta rota gera um **token de upload**: uma credencial temporária, válida por 5 minutos, que só serve para enviar documentos de uma subconta em [`POST /v1/document-uploads`](/referencia/fast-connect/enviar-documentos-com-token). Com ele, o upload pode sair direto do navegador do vendedor, sem que a chave secreta saia do seu servidor. É também o único caminho para enviar os documentos pessoais de um **sócio adicional**. ## Quando usar | Situação | Como usar esta rota | | - | - | | Documentos pessoais de um sócio adicional | Envie o `legalRepresentativeId` do sócio | | Tela de upload no navegador do vendedor | Gere o token no seu servidor e entregue só o token ao front-end | | Reenviar o documento de um sócio específico | Gere um token novo com o `legalRepresentativeId` dele e reenvie o arquivo | | Documentos do representante legal ou da empresa | Sem corpo (vincula ao representante legal), ou use [Enviar documentos](/referencia/fast-connect/enviar-documentos) | ## Antes de chamar * Tenha o `id` da subconta, devolvido em [Criar subconta](/referencia/fast-connect/criar-subconta). * Para um sócio, tenha o `id` dele: vem em `legalRepresentatives` na resposta da criação (itens com `isPrimary: false`) ou em [Listar representantes](/referencia/fast-connect/listar-representantes). * Autentique com a chave secreta (`sk_`) da **conta master**, sempre no servidor ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). ## Parâmetros de caminho **merchantId** `string` *required* Id da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. ## Corpo da requisição Formato `application/json`. O corpo é opcional. **legalRepresentativeId** `string` Sócio ao qual os documentos de pessoa (`responsible_document_front`, `responsible_document_back`, `selfie_with_document`) serão vinculados. Precisa pertencer à subconta; caso contrário, a resposta é `404`. Quando omitido, os documentos ficam no representante legal. Ex.: `2vorkEbbbCccDddEeeFffGggHhh`. > [!NOTE] > > O `legalRepresentativeId` só afeta documentos de pessoa. Documentos de empresa (`cnpj_card`, `social_contract`, `irs_letter`) valem para a subconta como um todo, com ou sem sócio no token. ## Respostas **token** `string` Token de upload. Use no cabeçalho `Authorization: Bearer` da chamada [`POST /v1/document-uploads`](/referencia/fast-connect/enviar-documentos-com-token). Ex.: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`. **expiresIn** `integer` Validade do token em segundos. Ex.: `300` (5 minutos). | HTTP | Significado | Corpo | | - | - | - | | `201` | Token emitido | `token`, `expiresIn` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `404` | Representante legal não encontrado (não pertence à subconta) | `{"statusCode": 404, "message": "Representante legal não encontrado"}` | > [!WARNING] > > O token expira em **300 segundos** (5 minutos) e é de **uso único**. Gere o token no momento do envio. Token vencido é recusado com `401` "Token de upload inválido ou expirado"; token já usado, com `403` "Token de upload expirado ou já utilizado". Nos dois casos, gere outro token. > [!TIP] > > **Para o desenvolvedor:** a subconta e o sócio ficam gravados **dentro do token**. O front-end recebe só o token e não consegue trocar de subconta ou de sócio. Gere um token por sócio: um token emitido para Bruno vincula os documentos de pessoa a Bruno, mesmo que o arquivo seja de outra pessoa. > [!NOTE] > > **Para o negócio:** com o token, cada sócio pode enviar os próprios documentos por um link ou tela do seu sistema, e a chave secreta da sua conta continua guardada no servidor. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` "Representante legal não encontrado" | `legalRepresentativeId` de outra subconta ou inexistente | Confira os ids com [Listar representantes](/referencia/fast-connect/listar-representantes) para esse `merchantId` | | `401` | Chave ausente, inválida ou mal codificada no Basic | Codifique `chave:` em Base64 (com os dois-pontos no fim) | | Upload recusado com `401` minutos depois | Token vencido (300 segundos) | Gere um token novo logo antes do envio | | Segundo upload recusado com `403` | O token é de uso único | Gere um token para cada envio | | Documentos do sócio aparecem no representante legal | Token emitido sem `legalRepresentativeId` | Envie o id do sócio no corpo | ```http REST (JSON) theme={null} POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const merchantId = '36OO3bcGjhPjjF3tzrqOGcmQuKo'; const response = await fetch( `https://api-global.fastpaybrasil.com/v1/submerchants/${merchantId}/document/upload-token`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ legalRepresentativeId: '2vorkEbbbCccDddEeeFffGggHhh' }), }, ); const { token, expiresIn } = await response.json(); // Entregue apenas o token ao front-end; ele vale por expiresIn segundos ``` ```python Python theme={null} import os import requests payload = { "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2vorkEbbbCccDddEeeFffGggHhh', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "legalRepresentativeId" => "2vorkEbbbCccDddEeeFffGggHhh", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 300 } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Representante legal não encontrado" } ``` ## Veja também > [card] [Enviar documentos com token](/referencia/fast-connect/enviar-documentos-com-token) > > Upload usando o token gerado aqui. > [card] [Sócios e documentos](/guias/fast-connect/socios-e-documentos) > > Fluxo completo de documentos por sócio. > [card] [Listar representantes](/referencia/fast-connect/listar-representantes) > > Ids dos sócios e status dos documentos. > [card] [Criar subconta](/referencia/fast-connect/criar-subconta) > > Cadastro com sócios adicionais. # Enviar documentos da subconta Source: https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos POST /v1/submerchants/{id}/document Envia os documentos da empresa e do representante legal para a análise de credenciamento da subconta. Depois de criar a subconta, a Finvia precisa dos documentos da empresa e do representante legal para fazer o credenciamento (KYC). Esta rota recebe esses arquivos direto do seu servidor, autenticada com a chave secreta da conta master. Os documentos de pessoa enviados aqui ficam sempre ligados ao **representante legal** (principal). ## Quando usar | Situação | Rota indicada | | - | - | | Subconta com um único representante, upload feito pelo seu servidor | Esta rota | | Documentos de empresa (`cnpj_card`, `social_contract`, `irs_letter`) | Esta rota ou o fluxo com token: valem para a subconta como um todo | | Documentos pessoais de um **sócio adicional** | [Criar token de upload](/referencia/fast-connect/criar-token-upload) com o `legalRepresentativeId` do sócio e [Enviar documentos com token](/referencia/fast-connect/enviar-documentos-com-token) | | Upload feito do navegador do vendedor, sem expor a chave secreta | Fluxo com token | > [!NOTE] > > Se a subconta tem só um representante (sem `additionalRepresentatives`), esta rota é tudo o que você precisa. Integrações que já usam esta rota continuam funcionando sem mudança. ## Antes de chamar * Tenha o `id` da subconta, devolvido em [Criar subconta](/referencia/fast-connect/criar-subconta). * Autentique com a chave secreta (`sk_`) da **conta master** ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * Os arquivos precisam estar em **JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF**, com no máximo **50 MB** cada. * Envie antes da aprovação: depois que a subconta é aprovada, novos uploads são bloqueados (`422`). * Confira quais documentos o credenciamento exige em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). ## Parâmetros de caminho **id** `string` *required* Identificador único da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. ## Corpo da requisição Formato `multipart/form-data`, obrigatório. O nome de cada campo é o tipo do documento. Nenhum campo é obrigatório sozinho, mas a requisição precisa ter **pelo menos um arquivo** (`minProperties: 1`). Você pode enviar vários documentos na mesma chamada ou um por chamada. **cnpj\_card** `file` Cartão CNPJ da empresa (tipo `string`, formato `binary`). Documento de empresa. **social\_contract** `file` Contrato social da empresa (tipo `string`, formato `binary`). Documento de empresa. **responsible\_document\_front** `file` Frente do documento de identificação do representante legal (tipo `string`, formato `binary`). Documento de pessoa. **responsible\_document\_back** `file` Verso do documento de identificação do representante legal (tipo `string`, formato `binary`). Documento de pessoa. **selfie\_with\_document** `file` Selfie do representante legal segurando o documento (tipo `string`, formato `binary`). Documento de pessoa. **irs\_letter** `file` IRS letter, usada no fluxo de cadastro de LLC (tipo `string`, formato `binary`). Documento de empresa. | Documento | Campo | Vinculado a | | - | - | - | | Cartão CNPJ | `cnpj_card` | Subconta | | Contrato social | `social_contract` | Subconta | | IRS letter (LLC) | `irs_letter` | Subconta | | Documento, frente | `responsible_document_front` | Representante legal | | Documento, verso | `responsible_document_back` | Representante legal | | Selfie com documento | `selfie_with_document` | Representante legal | Qualquer outro nome de campo é recusado com `400` `Invalid document name`. Não há campo para o certificado de MEI: para enviar esse documento, fale com o suporte da Finvia. > [!WARNING] > > Esta rota **não** diferencia sócios. Documentos de pessoa enviados aqui sempre ficam no representante legal. Se você enviar aqui a identidade de um sócio adicional, ela será registrada como documento do representante principal. Para sócios, use o fluxo com token. ## Respostas A resposta `201` não tem corpo. O sucesso é indicado pelo código HTTP. | HTTP | Significado | Corpo | | - | - | - | | `201` | Documentos enviados | Sem conteúdo | | `400` | Tipo de arquivo não aceito, arquivo acima de 50 MB ou nenhum arquivo | Mensagem padrão de validação. Ex.: `Validation failed (current file type is text/plain, expected type is ...)` ou `File is required` | | `400` | Nome de campo fora da lista | `{"statusCode": 400, "message": "Invalid document name", "error": "Bad Request"}` | | `400` | Subconta que não pertence à conta master | `{"statusCode": 400, "message": "Bad Request"}` | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` | | `422` | Subconta já aprovada: os documentos não podem mais ser alterados | `{"statusCode": 422, "message": "Unprocessable Entity"}` | Esta rota usa o corpo de erro padrão (`statusCode`, `message`, `error`), sem os códigos próprios da [rota com token](/referencia/fast-connect/enviar-documentos-com-token). Trate o erro pelo código HTTP. > [!TIP] > > Cada arquivo foi aceito quando a resposta é `201`. Para conferir os documentos de pessoa e o status de análise de cada um, use [Listar representantes](/referencia/fast-connect/listar-representantes) com `include=documents`. > [!NOTE] > > **Para o negócio:** no roteiro de homologação, o cenário FC-02 pede um envio por tipo: contrato social, cartão CNPJ, documento do responsável (frente e verso) e selfie com documento. Peça esses arquivos ao vendedor já no cadastro, para enviar tudo logo depois de criar a subconta. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` `Validation failed (...)` | Formato fora da lista aceita (ex.: HEIC, DOCX) ou arquivo acima de 50 MB | Converta para JPEG, PNG ou PDF e reduza o tamanho | | `400` `File is required` | Requisição sem arquivo | Envie pelo menos um dos seis campos | | `400` `Invalid document name` | Nome de campo fora da lista (ex.: `mei_certificate`) | Use um dos seis nomes desta página | | `422` `Unprocessable Entity` | Subconta já aprovada | Fale com a Finvia se precisar atualizar documentos | | Documento do sócio ficou no representante principal | Rota direta usada para sócio adicional | Use o fluxo com token e o `legalRepresentativeId` do sócio | ```http REST (JSON) theme={null} POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: multipart/form-data; boundary=----FinviaBoundary ------FinviaBoundary Content-Disposition: form-data; name="cnpj_card"; filename="cartao-cnpj.pdf" ------FinviaBoundary Content-Disposition: form-data; name="social_contract"; filename="contrato-social.pdf" ------FinviaBoundary Content-Disposition: form-data; name="responsible_document_front"; filename="rg-frente.jpg" ------FinviaBoundary Content-Disposition: form-data; name="responsible_document_back"; filename="rg-verso.jpg" ------FinviaBoundary Content-Disposition: form-data; name="selfie_with_document"; filename="selfie.jpg" ------FinviaBoundary-- ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document" \ -u "$FINVIA_API_KEY:" \ -F "cnpj_card=@./cartao-cnpj.pdf" \ -F "social_contract=@./contrato-social.pdf" \ -F "responsible_document_front=@./rg-frente.jpg" \ -F "responsible_document_back=@./rg-verso.jpg" \ -F "selfie_with_document=@./selfie.jpg" ``` ```javascript Node.js theme={null} import { readFile } from 'node:fs/promises'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const id = '36OO3bcGjhPjjF3tzrqOGcmQuKo'; const form = new FormData(); form.append('cnpj_card', new Blob([await readFile('./cartao-cnpj.pdf')], { type: 'application/pdf' }), 'cartao-cnpj.pdf'); form.append('social_contract', new Blob([await readFile('./contrato-social.pdf')], { type: 'application/pdf' }), 'contrato-social.pdf'); form.append('responsible_document_front', new Blob([await readFile('./rg-frente.jpg')], { type: 'image/jpeg' }), 'rg-frente.jpg'); form.append('responsible_document_back', new Blob([await readFile('./rg-verso.jpg')], { type: 'image/jpeg' }), 'rg-verso.jpg'); form.append('selfie_with_document', new Blob([await readFile('./selfie.jpg')], { type: 'image/jpeg' }), 'selfie.jpg'); // Não defina Content-Type: o fetch monta o boundary do multipart const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants/${id}/document`, { method: 'POST', headers: { Authorization: `Basic ${credentials}` }, body: form, }); if (response.status !== 201) { console.error(await response.json()); } ``` ```python Python theme={null} import os import requests files = { "cnpj_card": open("./cartao-cnpj.pdf", "rb"), "social_contract": open("./contrato-social.pdf", "rb"), "responsible_document_front": open("./rg-frente.jpg", "rb"), "responsible_document_back": open("./rg-verso.jpg", "rb"), "selfie_with_document": open("./selfie.jpg", "rb"), } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document", auth=(os.environ["FINVIA_API_KEY"], ""), files=files, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_POSTFIELDS => [ 'cnpj_card' => new CURLFile('./cartao-cnpj.pdf', null, 'cartao-cnpj.pdf'), 'social_contract' => new CURLFile('./contrato-social.pdf', null, 'contrato-social.pdf'), 'responsible_document_front' => new CURLFile('./rg-frente.jpg', null, 'rg-frente.jpg'), 'responsible_document_back' => new CURLFile('./rg-verso.jpg', null, 'rg-verso.jpg'), 'selfie_with_document' => new CURLFile('./selfie.jpg', null, 'selfie.jpg'), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String boundary = "FinviaBoundary"; ByteArrayOutputStream form = new ByteArrayOutputStream(); String[][] files = { {"cnpj_card", "./cartao-cnpj.pdf"}, {"social_contract", "./contrato-social.pdf"}, {"responsible_document_front", "./rg-frente.jpg"}, {"responsible_document_back", "./rg-verso.jpg"}, {"selfie_with_document", "./selfie.jpg"}, }; for (String[] file : files) { Path path = Path.of(file[1]); form.write(("--" + boundary + "\r\n" + "Content-Disposition: form-data; name=\"" + file[0] + "\"; filename=\"" + path.getFileName() + "\"\r\n" + "Content-Type: application/octet-stream\r\n\r\n").getBytes()); form.write(Files.readAllBytes(path)); form.write("\r\n".getBytes()); } form.write(("--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); using var form = new MultipartFormDataContent(); form.Add(new ByteArrayContent(File.ReadAllBytes("./cartao-cnpj.pdf")), "cnpj_card", "cartao-cnpj.pdf"); form.Add(new ByteArrayContent(File.ReadAllBytes("./contrato-social.pdf")), "social_contract", "contrato-social.pdf"); form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-frente.jpg")), "responsible_document_front", "rg-frente.jpg"); form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-verso.jpg")), "responsible_document_back", "rg-verso.jpg"); form.Add(new ByteArrayContent(File.ReadAllBytes("./selfie.jpg")), "selfie_with_document", "selfie.jpg"); var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document"); request.Content = form; var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" "path/filepath" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) files := [][2]string{ {"cnpj_card", "./cartao-cnpj.pdf"}, {"social_contract", "./contrato-social.pdf"}, {"responsible_document_front", "./rg-frente.jpg"}, {"responsible_document_back", "./rg-verso.jpg"}, {"selfie_with_document", "./selfie.jpg"}, } for _, file := range files { part, err := writer.CreateFormFile(file[0], filepath.Base(file[1])) if err != nil { panic(err) } content, err := os.ReadFile(file[1]) if err != nil { panic(err) } part.Write(content) } writer.Close() req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document", &form) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", writer.FormDataContentType()) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request.set_form( [ ["cnpj_card", File.open("./cartao-cnpj.pdf")], ["social_contract", File.open("./contrato-social.pdf")], ["responsible_document_front", File.open("./rg-frente.jpg")], ["responsible_document_back", File.open("./rg-verso.jpg")], ["selfie_with_document", File.open("./selfie.jpg")], ], "multipart/form-data" ) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 201 theme={null} (sem corpo) ``` ```json 400 theme={null} { "statusCode": 400, "message": "Invalid document name", "error": "Bad Request" } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 422 theme={null} { "statusCode": 422, "message": "Unprocessable Entity" } ``` ## Veja também > [card] [Sócios e documentos](/guias/fast-connect/socios-e-documentos) > > Quando usar a rota direta e quando usar o token. > [card] [Criar token de upload](/referencia/fast-connect/criar-token-upload) > > Token para sócios e uploads pelo navegador. > [card] [Listar representantes](/referencia/fast-connect/listar-representantes) > > Status de análise de cada documento. > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Fluxo completo de credenciamento. # Enviar documentos com token Source: https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token POST /v1/document-uploads Envia documentos da subconta usando um token de upload, sem a chave secreta, inclusive do navegador e por sócio. Esta rota recebe os documentos de uma subconta autenticada por um **token de upload**, gerado antes em [Criar token de upload](/referencia/fast-connect/criar-token-upload). A subconta e o eventual sócio são lidos de dentro do token; o corpo leva só os arquivos. Por isso a chamada pode sair do navegador do vendedor sem expor a chave secreta, e é por ela que os documentos de cada sócio adicional chegam à Finvia. ## Quando usar | Situação | Como usar esta rota | | - | - | | Documentos pessoais de um sócio adicional | Use um token emitido com o `legalRepresentativeId` do sócio | | Upload pelo navegador ou aplicativo do vendedor | Seu servidor gera o token; o front-end envia os arquivos com ele | | Substituir o documento de um sócio | Reenvie o documento com um token daquele sócio. Só o documento dele é substituído | | Upload feito pelo seu servidor, só com representante legal | Você também pode usar [Enviar documentos](/referencia/fast-connect/enviar-documentos) com a chave secreta | ## Antes de chamar * Gere o token com [`POST /v1/submerchants/{merchantId}/document/upload-token`](/referencia/fast-connect/criar-token-upload). Ele expira em 300 segundos e vale para um único envio. * Os arquivos precisam estar em **PDF ou imagem (JPG, PNG, GIF, BMP ou WebP)**, com no máximo **50 MB** cada. * Confira quais documentos o credenciamento exige em [Regras de credenciamento](/guias/fast-connect/regras-de-credenciamento). Não há campo para o certificado de MEI: para esse documento, fale com o suporte da Finvia. ## Autenticação Envie o token de upload no cabeçalho `Authorization: Bearer`. Esta rota **não** aceita a chave de API. **Authorization** `string` *required* `Bearer` seguido do token devolvido em `token` por [Criar token de upload](/referencia/fast-connect/criar-token-upload). Ex.: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`. ## Corpo da requisição Formato `multipart/form-data`, obrigatório. O **nome de cada campo é o nome do documento**. Nenhum campo é obrigatório sozinho, mas a requisição precisa ter pelo menos um arquivo (`minProperties: 1`). **cnpj\_card** `file` Cartão CNPJ da empresa (tipo `string`, formato `binary`). Documento de empresa. **social\_contract** `file` Contrato social da empresa (tipo `string`, formato `binary`). Documento de empresa. **responsible\_document\_front** `file` Frente do documento de identificação (tipo `string`, formato `binary`). Documento de pessoa: fica no sócio do token ou, sem sócio, no representante legal. **responsible\_document\_back** `file` Verso do documento de identificação (tipo `string`, formato `binary`). Documento de pessoa. **selfie\_with\_document** `file` Selfie segurando o documento (tipo `string`, formato `binary`). Documento de pessoa. **irs\_letter** `file` IRS letter, usada no fluxo de cadastro de LLC (tipo `string`, formato `binary`). Documento de empresa. > [!NOTE] > > O contrato descreve os campos de pessoa como documentos "do representante legal" porque o esquema é o mesmo da rota direta. Nesta rota, eles vão para o sócio indicado no token. | Tipo | Campos | Vinculado a | | - | - | - | | Documentos de empresa | `cnpj_card`, `social_contract`, `irs_letter` | Subconta como um todo. Não usam o vínculo por sócio | | Documentos de pessoa | `responsible_document_front`, `responsible_document_back`, `selfie_with_document` | Sócio do token (`legalRepresentativeId`) ou, sem sócio, representante legal | ## Respostas A resposta `201` não tem corpo. | HTTP | Significado | Corpo | | - | - | - | | `201` | Documentos enviados | Sem conteúdo | | `400` | `NO_FILE_SENT`: nenhum arquivo | `{"error": "NO_FILE_SENT", "message": "Nenhum arquivo foi enviado."}` | | `400` | `INVALID_DOCUMENT_NAME`: nome de campo fora da lista | `{"error": "INVALID_DOCUMENT_NAME", "message": "Tipo de documento inválido para este envio."}` | | `401` | Token ausente, com assinatura inválida ou vencido | `{"statusCode": 401, "message": "Token de upload inválido ou expirado"}` | | `403` | Token já usado | `{"statusCode": 403, "message": "Token de upload expirado ou já utilizado"}` | | `413` | `FILE_TOO_LARGE`: arquivo acima de 50 MB | `{"error": "FILE_TOO_LARGE", "message": "O arquivo excede o tamanho máximo de 50 MB.", "details": {...}}` | | `415` | `UNSUPPORTED_FILE_TYPE`: tipo de arquivo não aceito | `{"error": "UNSUPPORTED_FILE_TYPE", "message": "Tipo de arquivo não suportado. Envie PDF ou imagem (JPG, PNG, GIF, BMP ou WebP).", "details": {...}}` | | `422` | `DOCUMENT_NOT_EDITABLE`: subconta já aprovada | `{"error": "DOCUMENT_NOT_EDITABLE", "message": "Este documento não pode mais ser alterado no cadastro atual."}` | ### Dois formatos de erro * **Erros do arquivo** (`400`, `413`, `415`, `422`) vêm como `{ "error": "", "message": "...", "details": { ... } }`, sem `statusCode`. Decida pelo campo `error`, que é estável. No `413`, `details` traz `maxMb` e `actualMb`; no `415`, `allowed` e `actualType`. * **Erros do token** (`401`, `403`) vêm no formato padrão `{ statusCode, message, error }`. Trate o erro pelo código HTTP e pelo campo `error`, não pelo texto de `message`. > [!WARNING] > > Reenviar um documento de pessoa **substitui apenas o documento daquele sócio**. Se o token foi emitido para o sócio errado, o documento substituído será o desse sócio. Confira o `legalRepresentativeId` antes de gerar o token. > [!TIP] > > Depois do `201`, confira em [Listar representantes](/referencia/fast-connect/listar-representantes) com `include=documents`: o sócio passa a ter `idFront`, `idBack` e `selfie` com o status de análise. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` "Token de upload inválido ou expirado" | Token vencido (300 segundos), ausente ou inválido | Gere um token novo e envie logo em seguida | | `401` usando a chave secreta | Esta rota não aceita a chave de API | Use `Authorization: Bearer` com o token de upload | | `403` "Token de upload expirado ou já utilizado" | O token já foi usado em outro envio | Gere um token para cada envio | | `400` `NO_FILE_SENT` | Nenhum arquivo no multipart, ou campos sem arquivo | Envie pelo menos um arquivo nos campos aceitos | | `400` `INVALID_DOCUMENT_NAME` | Nome de campo fora da lista | Use um dos seis nomes desta página | | `413` `FILE_TOO_LARGE` | Arquivo acima de 50 MB | Reduza a resolução ou comprima o PDF | | `415` `UNSUPPORTED_FILE_TYPE` | Formato fora da lista (ex.: HEIC, DOCX) | Converta para JPG, PNG ou PDF | | `422` `DOCUMENT_NOT_EDITABLE` | Subconta já aprovada | Fale com a Finvia se precisar atualizar documentos | > [!TIP] > > **Para o desenvolvedor:** ao usar `FormData`, não defina o cabeçalho `Content-Type` manualmente. O `fetch` monta o valor `multipart/form-data` com o separador (boundary) correto. ```http REST (JSON) theme={null} POST /v1/document-uploads HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Bearer Content-Type: multipart/form-data; boundary=----FinviaBoundary ------FinviaBoundary Content-Disposition: form-data; name="responsible_document_front"; filename="rg-frente.jpg" ------FinviaBoundary Content-Disposition: form-data; name="responsible_document_back"; filename="rg-verso.jpg" ------FinviaBoundary Content-Disposition: form-data; name="selfie_with_document"; filename="selfie.jpg" ------FinviaBoundary-- ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/document-uploads" \ -H "Authorization: Bearer $UPLOAD_TOKEN" \ -F "responsible_document_front=@./rg-frente.jpg" \ -F "responsible_document_back=@./rg-verso.jpg" \ -F "selfie_with_document=@./selfie.jpg" ``` ```javascript Node.js theme={null} // No navegador: uploadToken foi gerado pelo seu servidor const form = new FormData(); form.append('responsible_document_front', fileInputFront.files[0]); form.append('responsible_document_back', fileInputBack.files[0]); form.append('selfie_with_document', fileInputSelfie.files[0]); const response = await fetch('https://api-global.fastpaybrasil.com/v1/document-uploads', { method: 'POST', headers: { Authorization: `Bearer ${uploadToken}` }, body: form, }); if (response.status === 401 || response.status === 403) { // token vencido ou já usado: peça um novo ao seu servidor e tente de novo } else if (response.status !== 201) { const { error } = await response.json(); // ex.: FILE_TOO_LARGE, UNSUPPORTED_FILE_TYPE console.error(error); } ``` ```python Python theme={null} import os import requests files = { "responsible_document_front": open("./rg-frente.jpg", "rb"), "responsible_document_back": open("./rg-verso.jpg", "rb"), "selfie_with_document": open("./selfie.jpg", "rb"), } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/document-uploads", headers={"Authorization": f"Bearer {os.environ['UPLOAD_TOKEN']}"}, files=files, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('UPLOAD_TOKEN')], CURLOPT_POSTFIELDS => [ 'responsible_document_front' => new CURLFile('./rg-frente.jpg', null, 'rg-frente.jpg'), 'responsible_document_back' => new CURLFile('./rg-verso.jpg', null, 'rg-verso.jpg'), 'selfie_with_document' => new CURLFile('./selfie.jpg', null, 'selfie.jpg'), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; public class Exemplo { public static void main(String[] args) throws Exception { String boundary = "FinviaBoundary"; ByteArrayOutputStream form = new ByteArrayOutputStream(); String[][] files = { {"responsible_document_front", "./rg-frente.jpg"}, {"responsible_document_back", "./rg-verso.jpg"}, {"selfie_with_document", "./selfie.jpg"}, }; for (String[] file : files) { Path path = Path.of(file[1]); form.write(("--" + boundary + "\r\n" + "Content-Disposition: form-data; name=\"" + file[0] + "\"; filename=\"" + path.getFileName() + "\"\r\n" + "Content-Type: application/octet-stream\r\n\r\n").getBytes()); form.write(Files.readAllBytes(path)); form.write("\r\n".getBytes()); } form.write(("--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/document-uploads")) .header("Authorization", "Bearer " + System.getenv("UPLOAD_TOKEN")) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue( "Bearer", Environment.GetEnvironmentVariable("UPLOAD_TOKEN")); using var form = new MultipartFormDataContent(); form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-frente.jpg")), "responsible_document_front", "rg-frente.jpg"); form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-verso.jpg")), "responsible_document_back", "rg-verso.jpg"); form.Add(new ByteArrayContent(File.ReadAllBytes("./selfie.jpg")), "selfie_with_document", "selfie.jpg"); var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/document-uploads"); request.Content = form; var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" "path/filepath" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) files := [][2]string{ {"responsible_document_front", "./rg-frente.jpg"}, {"responsible_document_back", "./rg-verso.jpg"}, {"selfie_with_document", "./selfie.jpg"}, } for _, file := range files { part, err := writer.CreateFormFile(file[0], filepath.Base(file[1])) if err != nil { panic(err) } content, err := os.ReadFile(file[1]) if err != nil { panic(err) } part.Write(content) } writer.Close() req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/document-uploads", &form) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer "+os.Getenv("UPLOAD_TOKEN")) req.Header.Set("Content-Type", writer.FormDataContentType()) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/document-uploads") request = Net::HTTP::Post.new(uri) request["Authorization"] = "Bearer #{ENV.fetch("UPLOAD_TOKEN")}" request.set_form( [ ["responsible_document_front", File.open("./rg-frente.jpg")], ["responsible_document_back", File.open("./rg-verso.jpg")], ["selfie_with_document", File.open("./selfie.jpg")], ], "multipart/form-data" ) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 201 theme={null} (sem corpo) ``` ```json 400 theme={null} { "error": "NO_FILE_SENT", "message": "Nenhum arquivo foi enviado." } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Token de upload inválido ou expirado", "error": "Unauthorized" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Token de upload expirado ou já utilizado", "error": "Forbidden" } ``` ```json 413 theme={null} { "error": "FILE_TOO_LARGE", "message": "O arquivo excede o tamanho máximo de 50 MB.", "details": { "maxMb": 50, "actualMb": 62.4 } } ``` ```json 422 theme={null} { "error": "DOCUMENT_NOT_EDITABLE", "message": "Este documento não pode mais ser alterado no cadastro atual." } ``` ## Veja também > [card] [Criar token de upload](/referencia/fast-connect/criar-token-upload) > > Gere o token antes de enviar. > [card] [Sócios e documentos](/guias/fast-connect/socios-e-documentos) > > Fluxo completo de documentos por sócio. > [card] [Listar representantes](/referencia/fast-connect/listar-representantes) > > Confira os documentos enviados. > [card] [Enviar documentos](/referencia/fast-connect/enviar-documentos) > > Upload direto com a chave secreta. # Listar representantes da subconta Source: https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes GET /v1/submerchants/{merchantId}/legal-representatives Lista o representante legal e os sócios de uma subconta e, se pedido, os documentos de cada um com o status de análise. Esta rota mostra quem são as pessoas cadastradas em uma subconta: o representante legal (sempre o primeiro da lista) e os sócios adicionais. Com `include=documents`, ela também mostra os documentos pessoais de cada um e em que ponto está a análise de cada arquivo. É a forma de saber quais documentos faltam e quais foram rejeitados. ## Quando usar | Situação | Como usar esta rota | | - | - | | Recuperar o `id` de um sócio para gerar um token de upload | Chame sem `include` | | Saber quais documentos pessoais ainda faltam | Chame com `include=documents` e confira as chaves ausentes em `documents` | | Mostrar ao vendedor o motivo de rejeição de um documento | Use `status` e `rejectionReason` de cada documento | | Exibir o documento enviado para conferência interna | Use a `url` assinada, que vale por 1 hora | ## Antes de chamar * Tenha o `id` da subconta (`merchantId`), devolvido em [Criar subconta](/referencia/fast-connect/criar-subconta). * Autentique com a chave secreta (`sk_`) da **conta master** à qual a subconta pertence ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). A master precisa ter o Connect habilitado; sem isso, a resposta é `403`. ## Parâmetros **merchantId** `string` *required* Id da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. **include** `string` Use `documents` para incluir os documentos de cada sócio. É o único valor aceito: qualquer outro devolve `400`. ## Respostas **data** `object[]` Representantes e sócios da subconta: o **representante legal primeiro** (`isPrimary: true`) e depois os sócios, por data de cadastro. **propriedades** **id** `string` Identificador do representante ou sócio. É o valor usado em `legalRepresentativeId` ao [criar um token de upload](/referencia/fast-connect/criar-token-upload). Ex.: `2vorkEaaaBbbCccDddEeeFffGgg`. **fullName** `string` Nome completo. Ex.: `Ana Lima`. **idNumber** `string | null` Número do documento de identificação (CPF, no Brasil). Ex.: `52998224725`. **email** `string` E-mail. Ex.: `ana.lima@email.com`. **isPrimary** `boolean` `true` apenas no representante legal da empresa. **documents** `object` Presente somente com `include=documents`, e pode vir vazio (`{}`). Chave ausente significa documento **não enviado**. **propriedades** **idFront** `object` Frente do documento de identificação (esquema `RepresentativeDocument`, abaixo). **idBack** `object` Verso do documento de identificação (esquema `RepresentativeDocument`). **selfie** `object` Selfie com documento (esquema `RepresentativeDocument`). ### Documento (`RepresentativeDocument`) Cada item de `documents` tem estes campos: **id** `string` Identificador do documento. Ex.: `2vorkEdddEeeFffGggHhhIiiJjj`. **url** `string` URL **assinada** para visualizar o arquivo. Expira em **1 hora**: não armazene. Ex.: `https:///documents/abc123?X-Amz-Signature=...`. **status** `string` Status de análise do documento: `approved` se aprovado, `rejected` se reprovado e `pending` nos demais casos. **rejectionReason** `string | null` Motivo da rejeição, quando `status` é `rejected`. Ex.: `null`. **createdAt** `string` Data de envio (formato `date-time`). Ex.: `2026-08-05T14:30:00.000Z`. ### Como mapear os documentos A correspondência entre o nome do campo usado no upload (fieldname) e a chave em `documents` é fixa: | Fieldname do upload | Chave em `documents` | | - | - | | `responsible_document_front` | `idFront` | | `responsible_document_back` | `idBack` | | `selfie_with_document` | `selfie` | Só esses três documentos de pessoa aparecem. Os documentos da empresa (`cnpj_card`, `social_contract`, `irs_letter`) não são retornados por esta rota. ### A qual sócio cada documento fica ligado | Como o documento foi enviado | Fica com | | - | - | | Token de upload gerado com `legalRepresentativeId` | O sócio daquele `legalRepresentativeId` | | Token de upload gerado sem `legalRepresentativeId` | O representante legal (`isPrimary: true`) | | Rota [`POST /v1/submerchants/{id}/document`](/referencia/fast-connect/enviar-documentos) | O representante legal | | Documentos antigos, enviados antes do cadastro de sócios | O representante legal | Um reenvio substitui o anterior: aparece só o documento mais recente de cada tipo, por sócio. | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista de representantes | `data` | | `400` | `include` com valor diferente de `documents` | `{"statusCode": 400, "message": "...", "error": "Bad Request"}` | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` | | `404` | Subconta não encontrada ou que não pertence à conta master autenticada | `{"statusCode": 404, "message": "Merchant não encontrado"}` | > [!WARNING] > > As `url` dos documentos são assinadas e **expiram em 1 hora**. Não grave a URL no seu banco nem a envie por e-mail. Quando precisar exibir o arquivo, consulte esta rota de novo. > [!NOTE] > > **Para o negócio:** com `include=documents`, o time de operações vê, por sócio, o que já foi enviado, o que está em análise e o que foi rejeitado (com o motivo). Isso permite cobrar do vendedor só o documento que falta. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` "Merchant não encontrado" | `merchantId` de outra conta master, inexistente ou de outro ambiente | Use a chave da conta master dona da subconta, no mesmo ambiente | | `400` no `include` | Valor diferente de `documents` | Use `include=documents` | | `documents` ausente | Chamada sem `include=documents` | Acrescente `?include=documents` | | Falta `idBack` ou `selfie` em `documents` | Documento ainda não enviado | Envie o arquivo pelo fluxo com token, com o `id` do sócio | | Link do documento parou de abrir | URL assinada expirada (1 hora) | Consulte a rota de novo para obter uma URL nova | | Documento do sócio aparece no representante principal | Upload feito pela rota direta ou com token sem `legalRepresentativeId` | Reenvie com um token emitido para o sócio | ```http REST (JSON) theme={null} GET /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const merchantId = '36OO3bcGjhPjjF3tzrqOGcmQuKo'; const response = await fetch( `https://api-global.fastpaybrasil.com/v1/submerchants/${merchantId}/legal-representatives?include=documents`, { headers: { Authorization: `Basic ${credentials}` } }, ); const { data } = await response.json(); for (const person of data) { const docs = person.documents ?? {}; const missing = ['idFront', 'idBack', 'selfie'].filter((key) => !docs[key]); console.log(person.fullName, 'faltam:', missing); } ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/legal-representatives?include=documents") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "data": [ { "id": "2vorkEaaaBbbCccDddEeeFffGgg", "fullName": "Ana Lima", "idNumber": "52998224725", "email": "ana.lima@email.com", "isPrimary": true, "documents": { "idFront": { "id": "2vorkEdddEeeFffGggHhhIiiJjj", "url": "https:///documents/abc123?X-Amz-Signature=...", "status": "pending", "rejectionReason": null, "createdAt": "2026-08-05T14:30:00.000Z" }, "idBack": { "id": "2vorkEeeeFffGggHhhIiiJjjKkk", "url": "https:///documents/def456?X-Amz-Signature=...", "status": "approved", "rejectionReason": null, "createdAt": "2026-08-05T14:30:00.000Z" }, "selfie": { "id": "2vorkEfffGggHhhIiiJjjKkkLll", "url": "https:///documents/ghi789?X-Amz-Signature=...", "status": "rejected", "rejectionReason": "Documento ilegível", "createdAt": "2026-08-05T14:30:00.000Z" } } }, { "id": "2vorkEbbbCccDddEeeFffGggHhh", "fullName": "Joao Silva", "idNumber": "11144477735", "email": "joao.silva@email.com", "isPrimary": false, "documents": {} } ] } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Merchant não encontrado" } ``` ## Veja também > [card] [Sócios e documentos](/guias/fast-connect/socios-e-documentos) > > Fluxo de documentos por sócio. > [card] [Criar token de upload](/referencia/fast-connect/criar-token-upload) > > Token vinculado a um sócio. > [card] [Enviar documentos com token](/referencia/fast-connect/enviar-documentos-com-token) > > Upload dos documentos do sócio. > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Credenciamento da subconta. # Listar subcontas Source: https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas GET /v1/submerchants Lista as subcontas vinculadas à sua conta master, com filtros por status, busca, CNPJ, período de criação e conta bancária. Esta rota devolve todas as subcontas (SubMerchants) ligadas à sua conta master (MerchantMaster) no [Connect](/guias/fast-connect/visao-geral). É a visão de carteira do marketplace: quem está ativo, quem ainda está em análise, quem foi bloqueado e quanto cada subconta já movimentou. ## Quando usar | Situação | Como usar esta rota | | - | - | | Montar a tela de gestão de vendedores no seu sistema | Liste sem filtros e pagine com `page` e `size` | | Acompanhar a fila de credenciamento | Filtre por `status=pending&status=correcting` | | Encontrar uma subconta pelo CNPJ, nome ou e-mail | Use `search`, ou `companyTaxId` só com dígitos | | Ver quem entrou em um período | Use `createdFrom` e `createdTo` | | Achar vendedores sem conta bancária ativa | Filtre por `completeness=incomplete` | | Ver os dados de uma única subconta já conhecida | Use [Consultar subconta](/referencia/fast-connect/consultar-subconta) | ## Antes de chamar * O módulo Connect precisa estar habilitado pela Finvia na sua conta master. Sem isso, a resposta é `403`. * Autentique com a chave secreta (`sk_`) da **conta master**. A lista sempre se restringe às subcontas ligadas a ela ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). ## Parâmetros de consulta Todos os parâmetros são opcionais. Sem `orderBy`, a lista vem da subconta mais recente para a mais antiga. **status** `string[]` Filtra pelo status atual da subconta. Valores aceitos: `active`, `inactive`, `pending`, `pre_approved`, `correcting`, `rejected` e `blocked`. Qualquer outro valor devolve `400`. Para mais de um status, **repita o parâmetro**: `?status=pending&status=correcting`. Não use lista separada por vírgula: `?status=pending,correcting` não dá erro, mas devolve a lista vazia. **search** `string` Busca por trecho, sem diferenciar maiúsculas de minúsculas, na razão social, no nome fantasia, no e-mail de contato e no CNPJ (com ou sem máscara). Ex.: `loja exemplo`. **companyTaxId** `string` CNPJ exato da subconta, **somente dígitos**. Com máscara, não encontra nada. Ex.: `11222333000181`. **legalName** `string` Trecho da razão social. Diferencia maiúsculas de minúsculas. Ex.: `LOJA EXEMPLO`. **tradeName** `string` Trecho do nome fantasia. Diferencia maiúsculas de minúsculas. Ex.: `Loja Exemplo`. **createdFrom** `string` Data inicial de criação, no formato `AAAA-MM-DD`. Inclusiva, considerando o dia no fuso de São Paulo. Ex.: `2026-10-01`. **createdTo** `string` Data final de criação, no formato `AAAA-MM-DD`. Inclusiva, considerando o dia no fuso de São Paulo. Ex.: `2026-10-31`. **completeness** `string` `complete` traz as subcontas com conta bancária ativa; `incomplete`, as que não têm. **currency** `string` Não filtra subcontas. Limita à moeda informada as somas `totalSales` e `totalSplit` de cada item. Ex.: `BRL`. **page** `integer` (default: 1) Número da página, começando em `1`. **size** `integer` (default: 10) Quantidade de subcontas por página. Ex.: `20`. **orderBy** `string` Campos de ordenação com o **nome da coluna em snake\_case**, separados por vírgula. Use o prefixo `-` para ordem decrescente. Ex.: `legal_name,-created_at` (razão social em ordem crescente e, em caso de empate, as mais recentes primeiro). Nomes em camelCase, como `legalName`, geram erro `500`. **createdAt** `string` *deprecated* **Legado.** Compara igualdade exata com o momento da criação e, na prática, quase nunca encontra nada. Use `createdFrom` e `createdTo`. > [!NOTE] > > Os filtros `updatedAt`, `approvedAt`, `rejectedAt`, `blockedAt` e `inactivatedAt` também são **legados**: comparam igualdade exata com o momento do evento e quase nunca encontram resultado. Não use. > [!TIP] > > **Para o desenvolvedor:** para varrer toda a carteira, percorra as páginas até `page` ser igual a `pages`. Mais detalhes em [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia). ## Respostas **data** `object[]` Subcontas da página atual. **propriedades** **id** `string` Identificador único da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. **tradeName** `string` Nome fantasia. Ex.: `Loja Exemplo`. **legalName** `string` Razão social. Ex.: `LOJA EXEMPLO LTDA`. **companyTaxId** `string` CNPJ, só com dígitos. Ex.: `11222333000181`. **averageMonthlyRevenue** `number` Faturamento médio mensal informado no cadastro. O contrato descreve o campo como "decimal as string", mas o tipo declarado é `number`. Ex.: `5000`. **averageOrderValue** `number` Ticket médio informado no cadastro. O contrato descreve o campo como "decimal as string", mas o tipo declarado é `number`. Ex.: `100`. **productType** `string` Tipo de produto vendido: `digital`, `physical` ou `both`. **website** `string` Site da subconta (formato `uri`). Ex.: `https://loja.exemplo.com.br`. **gatewayId** `string` Identificador do gateway ligado à subconta. Ex.: `36O08tjxJCxtEFApVPyWbryktP3`. **approvedAt** `string | null` Data e hora da aprovação (formato `date-time`). Ex.: `2025-12-04T20:02:51.762Z`. **inactivatedAt** `string | null` Data e hora da inativação (formato `date-time`). Ex.: `null`. **status** `string` Status atual: `active`, `pending`, `pre_approved`, `correcting`, `inactive`, `rejected` ou `blocked`. **metrics** `object` Métricas agregadas da subconta. A descrição no contrato diz que o objeto é devolvido por `GET /v1/submerchants/{id}`. **propriedades** **totalVolume** `number` Volume total de cobranças da subconta (soma dos valores), em reais. Ex.: `15000`. **splitBalance** `number` Total recebido pela subconta via split, em reais. Ex.: `450`. **splitRate** `number` Percentual médio de split aplicado à subconta. Ex.: `3`. **contactEmail** `string` E-mail de contato (formato `email`). Ex.: `contato@lojaexemplo.com.br`. **productDescription** `string` Descrição dos produtos ou serviços. Ex.: `Venda de acessórios para celular.` **softDescriptor** `string | null` Nome que aparece na fatura do cartão do cliente. Ex.: `null`. **createdAt** `string` Data e hora de criação (formato `date-time`). Ex.: `2025-12-04T18:45:52.988Z`. **hasBankAccount** `boolean` Indica se a subconta tem conta bancária ativa. Ex.: `true`. **totalSales** `number` Soma das vendas da subconta. Com o parâmetro `currency`, considera só essa moeda. Ex.: `15000`. **totalSplit** `number` Soma recebida pela subconta via split. Com o parâmetro `currency`, considera só essa moeda. Ex.: `450`. **total** `integer` Total de subcontas em todas as páginas. Ex.: `100`. **page** `integer` Página atual. Ex.: `1`. **size** `integer` Subcontas por página. Ex.: `10`. **pages** `integer` Total de páginas. Ex.: `10`. > [!NOTE] > > O contrato desta rota não informa quais campos da subconta são sempre presentes. Trate qualquer campo como possivelmente ausente. ### Status da subconta | Status | O que significa para você | | - | - | | `pending` | Cadastro recebido, em análise | | `correcting` | A Finvia pediu correção de dados ou documentos. Só acontece a partir de `pending` ou `pre_approved`. Depois que a correção é reenviada, a subconta volta para a análise | | `pre_approved` | Documentos obrigatórios conferidos. A subconta está sendo credenciada nas adquirentes e aguarda a aprovação final, que só parte deste status | | `active` | Aprovada e apta a transacionar | | `rejected` | Reprovada | | `blocked` | Bloqueada | | `inactive` | Inativada | O ciclo completo e quais mudanças geram aviso estão em [Webhooks de conta](/guias/webhooks/conta). | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista devolvida | `data`, `total`, `page`, `size`, `pages` | | `400` | Valor de filtro inválido (ex.: `status` fora da lista) | `{"statusCode": 400, "message": ["..."], "error": "Bad Request"}` | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` | > [!NOTE] > > **Para o negócio:** com o filtro de `status` e o período de criação, o time de operações acompanha o funil de credenciamento dos vendedores: quantos entraram, quantos estão em correção, quantos foram aprovados. `completeness=incomplete` mostra quem ainda não cadastrou conta bancária. `totalSales` e `totalSplit` mostram o movimento de cada subconta. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` | Chave ausente, inválida ou mal codificada no Basic | Codifique `chave:` em Base64 (com os dois-pontos no fim) | | `403` `Fast Connect not enabled.` | Connect não habilitado na conta master | Peça a habilitação à Finvia | | Lista vazia com vários status | Status enviados separados por vírgula | Repita o parâmetro: `status=pending&status=correcting` | | Busca por CNPJ não encontra | `companyTaxId` enviado com máscara | Envie só dígitos, ou use `search`, que aceita com ou sem máscara | | Busca por nome não encontra | `legalName` e `tradeName` diferenciam maiúsculas de minúsculas | Use `search` | | Filtro por data não traz nada | Foi usado um filtro legado de data exata (`createdAt`, `approvedAt`...) | Use `createdFrom` e `createdTo` | | `500` ao ordenar | `orderBy` com nome em camelCase | Use snake\_case: `legal_name,-created_at` | ```http REST (JSON) theme={null} GET /v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -G "https://api-global.fastpaybrasil.com/v1/submerchants" \ -u "$FINVIA_API_KEY:" \ --data-urlencode "status=pending" \ --data-urlencode "status=correcting" \ --data-urlencode "createdFrom=2026-10-01" \ --data-urlencode "createdTo=2026-10-31" \ --data-urlencode "page=1" \ --data-urlencode "size=20" \ --data-urlencode "orderBy=legal_name,-created_at" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const params = new URLSearchParams([ ['status', 'pending'], ['status', 'correcting'], // repita o parâmetro para vários status ['createdFrom', '2026-10-01'], ['createdTo', '2026-10-31'], ['page', '1'], ['size', '20'], ['orderBy', 'legal_name,-created_at'], ]); const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); const { data, page, pages } = await response.json(); ``` ```python Python theme={null} import os import requests params = [ ("status", "pending"), ("status", "correcting"), ("createdFrom", "2026-10-01"), ("createdTo", "2026-10-31"), ("page", "1"), ("size", "20"), ("orderBy", "legal_name,-created_at"), ] response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/submerchants", auth=(os.environ["FINVIA_API_KEY"], ""), params=params, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "data": [ { "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "tradeName": "Loja Exemplo", "legalName": "LOJA EXEMPLO LTDA", "companyTaxId": "11222333000181", "averageMonthlyRevenue": 5000, "averageOrderValue": 100, "productType": "digital", "website": "https://loja.exemplo.com.br", "gatewayId": "36O08tjxJCxtEFApVPyWbryktP3", "approvedAt": null, "inactivatedAt": null, "status": "pending", "metrics": { "totalVolume": 0, "splitBalance": 0, "splitRate": 0 }, "contactEmail": "contato@lojaexemplo.com.br", "productDescription": "Venda de acessórios para celular.", "softDescriptor": null, "createdAt": "2026-10-20T18:45:52.988Z", "hasBankAccount": true, "totalSales": 0, "totalSplit": 0 } ], "total": 1, "page": 1, "size": 20, "pages": 1 } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Fast Connect not enabled." } ``` ## Veja também > [card] [Consultar subconta](/referencia/fast-connect/consultar-subconta) > > Dados e métricas de uma subconta. > [card] [Criar subconta](/referencia/fast-connect/criar-subconta) > > Cadastro de um novo vendedor. > [card] [Subcontas e KYC](/guias/fast-connect/subcontas-e-kyc) > > Fluxo de cadastro e credenciamento. > [card] [Webhooks de conta](/guias/webhooks/conta) > > Avisos de mudança de status da subconta. # Taxas e dados da subconta Source: https://docs.fastpaybrasil.com/referencia/fast-connect/taxas-e-dados GET /v1/fast-connect/sub-accounts/{id}/fees-info Devolve as taxas transacionais e de antecipação, a razão social e o CNPJ de uma subconta do Connect. Esta rota mostra as taxas configuradas para uma subconta (transacionais e de antecipação) junto com a razão social e o CNPJ dela. São as taxas efetivas: na cobrança, a API usa só as taxas da própria conta que cobra, sem consultar a conta master. Serve para conferir o que cada vendedor paga, montar simuladores de taxa no seu sistema e conciliar valores líquidos. ## Quando usar | Situação | Como usar esta rota | | - | - | | Mostrar ao vendedor as taxas que ele paga | Chame com a chave da conta master e o `id` da subconta | | A própria subconta consulta as taxas dela | Chame com a credencial da subconta; o `id` é ignorado | | Calcular o percentual de split considerando a taxa da Finvia | Use `fees` como base do cálculo ([Cálculo de split](/guias/fast-connect/calculo-split)) | | Conferir razão social e CNPJ de uma subconta | Use o objeto `merchant` | ## Antes de chamar * Para consultar como **conta master**, o módulo Connect precisa estar habilitado pela Finvia na sua conta (sem isso, `403`), e a subconta precisa estar ligada a ela. * Tenha o `id` da subconta, devolvido em [Criar subconta](/referencia/fast-connect/criar-subconta) ou em [Listar subcontas](/referencia/fast-connect/listar-subcontas). ## Autenticação Use a chave secreta (`sk_`) em Basic, como no resto da API. Veja [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes). ## Quem está autenticado muda a resposta O resultado depende do `id` informado e também de **qual conta** faz a chamada. | Conta autenticada | Comportamento | | - | - | | **Conta master** | Usa o `id` informado e devolve a subconta ligada a ela. `id` de subconta de outra conta master, `id` inexistente ou o `id` da própria conta master devolvem `404`. Exige o Connect habilitado na conta master; sem isso, `403` | | **Subconta** | Devolve **sempre os próprios dados**. O `id` é ignorado e o Connect não precisa estar habilitado | ## Parâmetros de caminho **id** `string` *required* Id (KSUID) da subconta. Obrigatório quando a chamada é feita pela conta master; ignorado quando é feita pela subconta. Ex.: `2v2TGGb4NHTQWCiMmnelz2WVOZP`. ## Respostas **merchant** `object` Dados cadastrais da subconta. **propriedades** **id** `string` Id (KSUID) da subconta. Ex.: `2v2TGGb4NHTQWCiMmnelz2WVOZP`. **legalName** `string` Razão social. Ex.: `LOJA EXEMPLO LTDA`. **companyTaxId** `string` CNPJ, só dígitos, com 14 caracteres. Ex.: `11222333000181`. **fees** `object[]` Taxas da subconta, em lista plana, ordenada por tipo, método, moeda e bandeira. Array vazio significa subconta sem taxas configuradas: as cobranças dela são recusadas até a configuração. **propriedades** **feeType** `string` Tipo da taxa: `tx_spread` (transacional) ou `anticipation` (antecipação). **paymentMethod** `string | null` Método de pagamento (ex.: `credit_card`, `pix`). `null` para taxas sem método associado. **currencyCode** `string | null` Código da moeda no padrão ISO 4217 (ex.: `BRL`). `null` quando não se aplica. **brand** `string | null` Bandeira do cartão (`visa`, `mastercard`, `elo`). `null` representa a taxa padrão, que vale para qualquer bandeira sem regra própria. **definition** `object` Composição da taxa. **propriedades** **fixed** `number` Taxa fixa por transação, na moeda do item. Ex.: `0.5` (R\$ 0,50 em `BRL`). **percentages** `number[]` Taxa percentual por parcela: índice `0` = à vista (1x) até índice `11` = 12x. Um único valor para taxas sem parcelamento. Ex.: `[2.99, 3.49, 3.99, 4.49, 4.99, 5.49, 5.99, 6.49, 6.99, 7.49, 7.99, 8.49]`. > [!NOTE] > > `fees` não traz a reserva financeira nem a taxa de saque da subconta. ### De onde vêm as taxas Na criação, a subconta recebe uma **cópia** das taxas vigentes da conta master. Depois disso, as taxas da subconta são independentes: alterar as taxas da master não muda as das subcontas já criadas. A Finvia pode replicar uma alteração para as subcontas por operação interna. Se a subconta chegar à pré-aprovação sem nenhuma taxa (por exemplo, porque a master não tinha taxas quando ela foi criada), ela recebe uma cópia das taxas padrão da plataforma naquele momento. ### Como chegar à taxa efetiva As taxas vêm **como estão cadastradas**. A rota não escolhe a linha da bandeira nem a parcela por você. Para a taxa transacional (`tx_spread`), siga os passos abaixo. **1. Filtre pelo tipo, método e moeda** Ex.: `feeType` `tx_spread`, `paymentMethod` `credit_card`, `currencyCode` `BRL`. **2. Procure a bandeira do cartão** Se existir uma linha com a `brand` da venda (ex.: `visa`), use essa linha. **3. Caia para a taxa padrão** Se não houver linha da bandeira, use a linha com `brand` `null`. **4. Escolha o percentual da parcela** O percentual é `definition.percentages[parcelas - 1]`. No exemplo, 3x usa o índice `2`: 3,99%. A taxa `definition.fixed` é cobrada por transação. Para a **antecipação** (`anticipation`), só `percentages[0]` é usado. É uma taxa **mensal**, multiplicada pelo número de meses até o vencimento da parcela (mínimo de 1 mês), e só incide quando o recebível é antecipado. Exemplo com `percentages[0]` igual a `1.99`: uma parcela que vence em 3 meses, se antecipada, paga 1,99% × 3 = 5,97% sobre o valor dela. > [!WARNING] > > `fees` vazio, ou sem linha para o método e a moeda da cobrança, significa que a subconta **não tem taxa configurada** para essa combinação. As cobranças dessa combinação são recusadas com `422` `Fees not configured`. Não interprete a lista vazia como taxa zero e não use as taxas da master no lugar: fale com o suporte da Finvia para configurar. | HTTP | Significado | Corpo | | - | - | - | | `200` | Taxas e dados cadastrais da subconta | `merchant`, `fees` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Não autorizado"}` | | `403` | Conta que não é merchant, ou Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect não habilitado para esta conta"}` | | `404` | Subconta não encontrada (não ligada, inexistente ou `id` da própria conta master) | `{"statusCode": 404, "message": "Subconta não encontrada"}` | > [!NOTE] > > **Para o negócio:** a Finvia aplica o percentual de split sobre o **valor líquido**, depois das taxas dela. Se a sua plataforma cobra uma comissão sobre o valor bruto da venda, use as taxas desta rota para chegar ao percentual certo. O passo a passo está em [Cálculo de split](/guias/fast-connect/calculo-split). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` "Connect não habilitado para esta conta" | Módulo Connect não habilitado na conta master | Peça a habilitação à Finvia | | `404` "Subconta não encontrada" | `id` de subconta de outra conta master, inexistente ou o `id` da própria conta master | Use o `id` de uma subconta ligada à sua conta | | Resposta traz dados de uma subconta diferente do `id` enviado | Chamada feita com a credencial de uma subconta, que sempre devolve os próprios dados | Use a chave da conta master para consultar outras subcontas | | `fees` vazio | Subconta sem taxas configuradas. As cobranças dela são recusadas com `422` `Fees not configured` | Fale com o suporte da Finvia para configurar as taxas | | Mudei as taxas da master e a subconta não mudou | As taxas são copiadas só na criação da subconta | Peça à Finvia a replicação para as subcontas | | Taxa de uma bandeira não aparece | Só existe a taxa padrão (`brand: null`) | Use a linha com `brand` `null` | ```http REST (JSON) theme={null} GET /v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const id = '2v2TGGb4NHTQWCiMmnelz2WVOZP'; const response = await fetch( `https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/${id}/fees-info`, { headers: { Authorization: `Basic ${credentials}` } }, ); const { merchant, fees } = await response.json(); // Taxa efetiva de cartão Visa em 3x: linha da bandeira ou, se não houver, a padrão function cardFee(fees, brand, installments) { const card = fees.filter( (f) => f.feeType === 'tx_spread' && f.paymentMethod === 'credit_card' && f.currencyCode === 'BRL', ); const row = card.find((f) => f.brand === brand) ?? card.find((f) => f.brand === null); if (!row) return null; // sem taxa: a cobrança seria recusada com 422 Fees not configured return { fixed: row.definition.fixed, percentage: row.definition.percentages[installments - 1], }; } console.log(cardFee(fees, 'visa', 3)); // { fixed: 0.5, percentage: 3.99 } ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "merchant": { "id": "2v2TGGb4NHTQWCiMmnelz2WVOZP", "legalName": "LOJA EXEMPLO LTDA", "companyTaxId": "11222333000181" }, "fees": [ { "feeType": "anticipation", "paymentMethod": "credit_card", "currencyCode": "BRL", "brand": null, "definition": { "fixed": 0, "percentages": [1.99] } }, { "feeType": "tx_spread", "paymentMethod": "credit_card", "currencyCode": "BRL", "brand": "visa", "definition": { "fixed": 0.5, "percentages": [2.99, 3.49, 3.99, 4.49, 4.99, 5.49, 5.99, 6.49, 6.99, 7.49, 7.99, 8.49] } } ] } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Não autorizado" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Fast Connect não habilitado para esta conta" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Subconta não encontrada" } ``` ## Veja também > [card] [Taxas no Connect](/guias/fast-connect/taxas) > > Como as taxas das subcontas funcionam. > [card] [Cálculo de split](/guias/fast-connect/calculo-split) > > Percentual de split considerando as taxas. > [card] [Consultar subconta](/referencia/fast-connect/consultar-subconta) > > Dados e status da subconta. > [card] [Visão geral do Connect](/guias/fast-connect/visao-geral) > > Conta master e subcontas. # Introdução à Referência Source: https://docs.fastpaybrasil.com/referencia/introducao URL base, autenticação, formato dos dados e como ler as páginas de endpoint da API da Finvia. Esta seção descreve cada rota da API da Finvia com todos os parâmetros, todos os campos de resposta e todos os códigos HTTP do contrato. Use os guias para entender **o fluxo** de um recurso (Pix, 3D Secure, estorno) e use a Referência para conferir **o detalhe** de uma chamada: nome exato do campo, tipo, se é obrigatório e o que volta. > [!NOTE] > > **Para o negócio:** cada página de endpoint começa com um parágrafo sobre para que a rota serve e uma tabela "Quando usar". Esses trechos ajudam a decidir o que pedir ao time técnico sem precisar ler os parâmetros. Os detalhes técnicos vêm logo depois. ## URL base Todas as rotas usam o mesmo endereço, em produção e no sandbox (ambiente de testes): ```text theme={null} https://api-global.fastpaybrasil.com ``` O ambiente é definido pela chave enviada. Com uma chave de teste (`sk_test_`, `pk_test_`), toda cobrança em `POST /v1/charges` é simulada, inclusive com cartão salvo. Com uma chave de produção (`sk_`, `pk_`), as transações são reais. O cadastro de cartão e as assinaturas não têm sandbox, e não existe saque no sandbox (veja o aviso em [Testar no playground](#testar-no-playground)). As rotas começam com `/v1`, por exemplo `GET /v1/charges`. Outros endereços: o painel fica em `https://app.finvia.com.br`, e o SDK de 3D Secure via CDN em `https://js.fastpaybrasil.com/security-sdk.min.js`. No 3DS gerenciado, use o endereço recebido em `authenticationUrl`, sem montar a URL. As URLs de documentos são assinadas e têm o domínio do provedor de armazenamento (nos exemplos, `https:///documents/...`): não fixe esse domínio. ## Autenticação A maior parte da API usa **HTTP Basic Auth** com a chave secreta: a chave vai no lugar do usuário, a senha fica vazia e o par `chave:` é convertido para Base64. ```text theme={null} Authorization: Basic c2tfYWJjMTIzOg== ``` O valor acima é o Base64 de `sk_abc123:`. Para conferir se o seu valor está certo, decodifique o Base64 e veja se ele termina com `:`. O passo a passo completo, com exemplos em várias linguagens, está em [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes). Nem todas as rotas usam a mesma credencial: | Credencial | Como enviar | Rotas | | - | - | - | | Chave secreta (`sk_`, `sk_test_`) | `Authorization: Basic` com `chave:` em Base64 | Todas as rotas não listadas abaixo: cobranças, estorno, clientes, cartões, planos, assinaturas, meios de pagamento, saldo (`GET /v1/wallets`), saques (`/v1/payout-requests` e o saque de subconta), domínios Apple Pay, subcontas, `fees-info` e endpoints de webhook | | Chave pública (`pk_`, `pk_test_`) | `Authorization: Basic` com `chave:` em Base64, usando a chave pública | Apple Pay: `POST /v1/apple-pay/validate-merchant`. 3D Secure: `POST /v1/three-ds/authenticate`, `POST /v1/three-ds/submit`, `POST /v1/three-ds/cancel`, `POST /v1/three-ds/challenge-result` e `POST /v1/charges/{id}/resume-3ds` | | Token de upload | `Authorization: Bearer` seguido do token gerado em `POST /v1/submerchants/{merchantId}/document/upload-token` | Só `POST /v1/document-uploads`. Esse token é diferente da chave de API | Fora o envio de documentos com token, toda chamada de integração usa uma das chaves da tabela. > [!WARNING] > > A chave **secreta** (`sk_`) nunca pode aparecer em código que roda no navegador ou no aplicativo do cliente. A chave **pública** (`pk_`) foi feita para o front-end e é a que você usa nas rotas de 3D Secure e na validação de sessão do Apple Pay. A conta precisa estar ativa para a `pk_` funcionar. A chave age com as permissões do usuário que a gerou. A chave de produção criada automaticamente pertence ao proprietário da conta e funciona em todas as rotas. Se for usar uma chave gerada por outro usuário, gere com um perfil **Owner** ou **Manager**: chaves de Desenvolvedor recebem `403` com `Acesso negado` ao criar cobranças, em saldo e em saques, e as de Desenvolvedor e Financeiro também nas rotas de planos e assinaturas (veja [Permissões da chave](/primeiros-passos/credenciais-e-ambientes#permissões-da-chave)). ## Formato dos dados | Item | Regra | Exemplo | | - | - | - | | Corpo das requisições e respostas | JSON, com `Content-Type: application/json` nas requisições com corpo | `{"chargeId": "2vorkDcXyvzifL63YX09S9VqcnI"}` | | Nomes de campos | camelCase na API | `paymentMethod`, `createdAt`, `pspRefId` | | Valores monetários | Em **reais** (decimal), na unidade da moeda | `10` = R\$ 10,00; `199.99` = R\$ 199,99 | | Datas | ISO 8601 (formato `date-time`) | `2023-01-15T14:30:00Z` | | Moedas | Código ISO 4217 | `BRL` | | Países | ISO 3166-1 alpha-3, em maiúsculas | `BRA` | Exceções que você vai encontrar: * Os itens da cobrança usam `unit_price` (com sublinhado), como está no contrato. * Os endpoints de webhook (`/v1/webhook-endpoints`) recebem o corpo em snake\_case (`enabled_events`, `include_submerchants`) e respondem em camelCase. * `orderBy` em `GET /v1/submerchants` usa os nomes das colunas em snake\_case (`legal_name,-created_at`). * Nas respostas de `GET` de cobrança, as chaves de `metadata` voltam em camelCase. Envie-as nesse formato para lê-las iguais em todos os canais (veja [Metadata](/guias/cobrancas/visao-geral#metadata)). * Valores de saque (`amount`, `payoutFee`, `netAmount`) e o `splitPercentage` do split chegam como texto decimal com 8 casas (ex.: `"100.00000000"`). Converta para número antes de calcular. * Os webhooks de cobrança e de assinatura usam snake\_case no primeiro nível de `data`, como `psp_ref_id` e `paid_at`; os objetos aninhados da cobrança ficam em camelCase. O postback `charge.updated`, os avisos de conta e os eventos de saque usam camelCase. Detalhes em [Webhooks de cobrança](/guias/webhooks/cobranca). ## Paginação, ordenação e idempotência * Todas as listagens paginadas recebem `page` (começa em `1`) e `size` (itens por página, padrão `10`). `limit` e outros parâmetros desconhecidos são ignorados sem erro. Algumas listagens devolvem um array simples, sem paginação, como `GET /v1/wallets`. * A maior parte das listagens tem ordem fixa, da mais recente para a mais antiga. `orderBy` só funciona em `GET /v1/submerchants`, com nomes em snake\_case. * O cabeçalho `Idempotency-Key` não existe hoje: depois de um timeout, siga o procedimento descrito em [Idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia#idempotência). Regras completas e exemplos em [Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia). ## Erros Os erros voltam com o código HTTP e um corpo JSON. Há três formatos: | Formato | Onde aparece | Exemplo | | - | - | - | | `{ statusCode, message, error }` | A maior parte das rotas. Em erros de validação de campos (`400`), `message` é uma lista | `{ "statusCode": 404, "message": "Cobrança não encontrada", "error": "Not Found" }` | | `{ code, message }` | Erros de negócio do Apple Pay e validação de cartão em `POST /v1/subscriptions` | `{ "code": "APPLE_PAY_DOMAIN_NOT_VERIFIED", "message": "..." }` | | `{ error, message, details }` | Erros de arquivo em `POST /v1/document-uploads` | `{ "error": "NO_FILE_SENT", "message": "Nenhum arquivo foi enviado." }` | ```json theme={null} { "statusCode": 400, "message": ["amount must be a positive number", "amount must not be less than 1"], "error": "Bad Request" } ``` | HTTP | Significado geral | | - | - | | `400` | Corpo inválido (validação) ou operação não permitida no estado atual | | `401` | Credencial ausente ou inválida | | `403` | A credencial não tem permissão para o recurso (`Acesso negado`), recurso não habilitado ou operação indisponível no Modo Teste | | `404` | Recurso não encontrado ou fora do escopo da sua chave | | `409` | Conflito, como CNPJ já cadastrado ou requisição simultânea | | `422` | Regra de negócio violada | | `429` | Limite de tentativas atingido | | `500` e `503` | Erro interno ou serviço indisponível | | `501` | Operação não disponível para o método ou provedor | Trate o erro pelo código HTTP e, quando existir, pelo campo `code` ou `error` dos dois últimos formatos. As mensagens misturam português e inglês e não devem ser comparadas como texto. Cada página de endpoint lista os códigos da rota. O tratamento recomendado está em [Erros e como tratar](/primeiros-passos/erros) e as mensagens de cada rota em [Códigos de erro](/anexos/codigos-de-erro). ## Como ler uma página de endpoint Toda página de endpoint segue a mesma ordem: **1. Cabeçalho** Método e rota (ex.: `POST /v1/refunds`) e o tipo de autenticação. **2. Para que serve, quando usar e antes de chamar** Contexto de negócio, situações de uso e pré-requisitos. **3. Parâmetros** Cada parâmetro aparece com o nome, onde ele vai (`path`, `query` ou `body`), o tipo e o selo **required** quando é obrigatório. Valores padrão aparecem como `default`. Limites (mínimo, máximo, tamanho) e valores aceitos (enums) ficam na descrição. **4. Respostas** Todos os campos da resposta de sucesso, seguidos de uma tabela com os códigos HTTP documentados. **5. Exemplos** Exemplo de requisição em cURL e Node.js e exemplos de resposta de sucesso e de erro, no painel lateral. Objetos aninhados ficam recolhidos. Clique em **propriedades** (ou no nome da variante, quando o campo pode ter formatos diferentes) para ver os campos internos. Quando um campo recebe um formato diferente por forma de pagamento, cada formato aparece em um bloco separado. > [!TIP] > > **Para o desenvolvedor:** um campo sem o selo **required** pode ser omitido na requisição. Na resposta, um tipo como `string | null` significa que o campo pode vir `null`. Escreva o seu código para tolerar campos ausentes e nulos sempre que o tipo indicar isso. ## Testar no playground As páginas de endpoint têm um botão para enviar a requisição direto do navegador. Use sempre uma **chave de teste** nesse recurso: * Em rotas com chave secreta, informe a chave `sk_test_` como usuário e deixe a senha vazia. * Nas rotas de 3D Secure, informe a chave pública de teste (`pk_test_`). * Em `POST /v1/document-uploads`, informe o token de upload. > [!WARNING] > > Não use a chave de produção no playground. Mesmo com a chave de teste, o cadastro de cartão (`POST /v1/cards`) registra o cartão de verdade (sem cobrar) e as assinaturas cobram de verdade. O cofre de cartões é o mesmo para teste e produção. ## Veja também > [card] [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) > > Como gerar as chaves e montar o cabeçalho. > [card] [Criar uma cobrança](/referencia/cobrancas/criar) > > A rota central da API. > [card] [Mapa da API](/mapa-da-api) > > Todas as rotas agrupadas por recurso. > [card] [Roteiro de homologação](/homologacao/roteiro) > > O que testar antes de ir para produção. # Listar meios de pagamento Source: https://docs.fastpaybrasil.com/referencia/meios-de-pagamento/listar GET /v1/payment-methods Mostra quais formas de pagamento estão habilitadas para a sua conta, com países e moedas aceitos em cada uma. Esta rota responde a uma pergunta direta: **quais formas de pagamento esta conta pode oferecer?** Para cada uma, ela informa os países onde funciona e as moedas aceitas. Use essa lista para montar as opções do seu checkout. A Finvia oferece cartão de crédito (inclusive cartão salvo e Apple Pay) e Pix. Ela também é a chamada mais simples para validar uma chave de API: uma resposta `200` confirma que a autenticação está correta. ## Quando usar | Situação | Como usar esta rota | | - | - | | Montar as opções do checkout | Liste e mostre só os meios retornados | | Mostrar só o que aceita a moeda do carrinho | Filtre por `currency`, por exemplo `BRL` | | Validar a chave de API logo depois de gerar | Chame sem filtros. `200` significa autenticação correta | | Conferir o que uma subconta pode oferecer | Filtre por `merchantId` | | Conferir o saldo da conta | Use [`GET /v1/wallets`](/referencia/carteiras/listar) | > [!NOTE] > > **Para o negócio:** as formas de pagamento disponíveis dependem da configuração da sua conta na Finvia. Se um meio que você espera não aparece na lista, fale com o seu contato comercial antes de pedir ao time técnico para integrar. ## Antes de chamar * Tenha uma chave secreta (`sk_` ou `sk_test_`) e monte o cabeçalho Basic ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). ## Parâmetros de consulta Nenhum parâmetro é obrigatório. **merchantId** `string` Filtra os meios de pagamento pelo ID do merchant. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **currency** `string` Filtra os meios de pagamento pela moeda (código ISO 4217). Ex.: `BRL`. ## Respostas A resposta `200` é um **array** de meios de pagamento, sem paginação. **id** `string` Identificador único do meio de pagamento. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **name** `string` Nome técnico do meio de pagamento. Ex.: `pix`. **countries** `string[]` Países onde o meio está disponível (ISO 3166-1 alpha-3). Ex.: `["BRA"]`. **currencies** `string[]` Moedas aceitas pelo meio (ISO 4217). Ex.: `["BRL"]`. **description** `string` Nome para exibir na tela. Ex.: `Pix`. > [!TIP] > > **Para o desenvolvedor:** use `description` como rótulo no checkout e `name` como chave no seu código. O contrato não garante que `name` seja igual ao `type` usado em `POST /v1/charges`. Confira os valores devolvidos na sua conta antes de mapear um para o outro. O exemplo desta página é ilustrativo. | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista obtida | Array de meios de pagamento | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Usuário dono da chave sem permissão para o recurso | `{ "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 }` | ## Exemplos por caso de uso > [tab] Validar a chave > > A primeira chamada depois de gerar a chave. > > ```bash theme={null} > curl -X GET "https://api-global.fastpaybrasil.com/v1/payment-methods" \ > -u "$FINVIA_API_KEY:" > ``` > > > [!TIP] > > > > Resposta `200` com um array (mesmo vazio) confirma que a chave e o cabeçalho estão corretos. > [tab] Opções por moeda > > Mostra só os meios que aceitam a moeda do carrinho. > > ```javascript theme={null} > const metodos = await listarMeios({ currency: 'BRL' }); > const opcoes = metodos.map((m) => ({ valor: m.name, rotulo: m.description })); > ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` | Cabeçalho ausente, chave inválida ou Base64 sem os dois pontos no final | Decodifique o Base64 e confira se termina em `:` | | `403` | A chave não tem permissão para o recurso. A chave herda as permissões do usuário que a gerou | Confira o perfil do usuário que gerou a chave ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)) | | Um meio esperado não aparece | O meio não está habilitado para a conta ou para a moeda filtrada | Consulte sem filtros e fale com o seu contato comercial | ```http REST (JSON) theme={null} GET /v1/payment-methods?currency=BRL HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL', { headers: { Authorization: `Basic ${credentials}` }, }); const paymentMethods = await response.json(); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} [ { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "name": "pix", "countries": ["BRA"], "currencies": ["BRL"], "description": "Pix" } ] ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 403 theme={null} { "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 } ``` ## Veja também > [card] [Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes) > > Gere a chave e faça a primeira chamada. > [card] [Formas de pagamento](/guias/cobrancas/visao-geral) > > Quando usar cada forma de pagamento. > [card] [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento) > > Guia de saldo, saque e meios de pagamento. > [card] [Consultar saldos](/referencia/carteiras/listar) > > Saldo por moeda. # Alterar status do plano Source: https://docs.fastpaybrasil.com/referencia/planos/alterar-status PATCH /v1/subscription-plans/{id}/status Ativa ou desativa um plano para novas assinaturas. A desativação pede uma confirmação em segunda etapa. Esta rota abre ou fecha um plano para novas vendas. Desativar um plano impede novas assinaturas nele, sem mexer nas assinaturas que já existem: elas continuam sendo cobradas normalmente. Por segurança, a desativação **sempre** acontece em duas etapas, com ou sem assinaturas ativas no plano: esta rota devolve um token de confirmação e o plano só fica inativo depois de [Confirmar desativação](/referencia/planos/confirmar-desativacao). A ativação é imediata. ## Quando usar | Situação | Como usar esta rota | | - | - | | Encerrar a venda de um plano antigo | `status` `inactive` e, em seguida, confirmar com o token | | Pausar uma oferta temporária | `status` `inactive` e confirmar. Reative depois com `active` | | Voltar a vender um plano desativado | `status` `active`. A ativação é imediata, sem confirmação | | Cancelar as assinaturas de quem já está no plano | Esta rota não faz isso. Use [Cancelar assinatura](/referencia/assinaturas/cancelar) em cada assinatura | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **atualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Tenha o `id` do plano. * Para desativar, prepare a aplicação para chamar a confirmação logo em seguida: o token vale por 5 minutos e só pode ser usado uma vez. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). ## Como funciona a desativação **1. Solicite a desativação** Chame esta rota com `{"status": "inactive"}`. A resposta traz sempre `requiresConfirmation: true` e um `confirmationToken`. Pedir a desativação de novo gera outro token e invalida o anterior. **2. Confirme em até 5 minutos** Envie o `confirmationToken` para `PATCH /v1/subscription-plans/{id}/status/confirm`. A resposta `204` indica que o plano foi desativado. O token é de uso único. **3. Confira o resultado** Consulte o plano: `status` passa a ser `inactive`. As assinaturas existentes seguem ativas e renovando normalmente. Para encerrá-las, cancele uma a uma. ## Parâmetros de caminho **id** `string` *required* Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Corpo da requisição **status** `string` *required* Novo status do plano: `active` ou `inactive`. Ex.: `inactive`. ## Respostas A resposta `200` nunca traz o objeto do plano. O formato depende do status pedido. | Pedido | Resposta `200` | Efeito | | - | - | - | | `{"status": "inactive"}` | `{ "requiresConfirmation": true, "confirmationToken": "..." }` | Nada muda até a confirmação | | `{"status": "active"}` | `{ "requiresConfirmation": false }` | O plano é ativado na hora | **requiresConfirmation** `boolean` `true` ao pedir a desativação (sempre). `false` ao ativar. **confirmationToken** `string` Só ao desativar. Token para [Confirmar desativação](/referencia/planos/confirmar-desativacao). Ex.: `abc123xyz`. Vale por 5 minutos e é de uso único. Um novo pedido de desativação gera outro token e invalida o anterior. | HTTP | Significado | Corpo | | - | - | - | | `200` | Desativação pedida (aguarda confirmação) ou plano ativado | `requiresConfirmation` e, ao desativar, `confirmationToken` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão atualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Plano não encontrado | `{"statusCode": 404, "message": "Subscription plan not found"}` | > [!NOTE] > > **Para o negócio:** desativar um plano tira o produto da prateleira, mas **não** encerra a receita recorrente de quem já assinou. Se a intenção é descontinuar o serviço por completo, além de desativar o plano é preciso cancelar cada assinatura, considerando as regras de cancelamento (estorno automático em até 7 dias da criação da assinatura). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | Plano continua `active` depois de pedir `inactive` | Faltou a segunda etapa | Chame [Confirmar desativação](/referencia/planos/confirmar-desativacao) com o `confirmationToken` | | `400` "Invalid or expired confirmation token" na confirmação | Token usado depois de 5 minutos, já usado, errado ou substituído por um pedido mais recente | Peça a desativação de novo e confirme com o token mais recente | | `404` com "Subscription plan not found" | `id` errado ou de outra conta | Confira o `id` na [listagem de planos](/referencia/planos/listar) | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão atualizar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Assinantes antigos continuam sendo cobrados | Comportamento documentado: desativar o plano não afeta assinaturas existentes | Cancele as assinaturas que precisam ser encerradas | ```http REST (JSON) theme={null} PATCH /v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "status": "inactive" } ``` ```bash cURL theme={null} curl -X PATCH "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{"status": "inactive"}' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const base = 'https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q'; const headers = { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' }; // 1. Solicita a desativação const res = await fetch(`${base}/status`, { method: 'PATCH', headers, body: JSON.stringify({ status: 'inactive' }), }); const body = await res.json(); // 2. Confirma em seguida (o token vale por 5 minutos) if (body.requiresConfirmation) { const confirm = await fetch(`${base}/status/confirm`, { method: 'PATCH', headers, body: JSON.stringify({ confirmationToken: body.confirmationToken }), }); // confirm.status === 204 indica plano desativado } ``` ```python Python theme={null} import os import requests payload = { "status": "inactive", } response = requests.request( "PATCH", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'inactive', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'PATCH', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "status": "inactive" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "status": "inactive" } """; var request = new HttpRequestMessage(HttpMethod.Patch, "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "status": "inactive" }`) req, err := http.NewRequest("PATCH", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status") request = Net::HTTP::Patch.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "status" => "inactive", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 Desativação theme={null} { "requiresConfirmation": true, "confirmationToken": "abc123xyz" } ``` ```json 200 Ativação theme={null} { "requiresConfirmation": false } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Subscription plan not found" } ``` ## Veja também > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Confirmar desativação](/referencia/planos/confirmar-desativacao) > > Segunda etapa da desativação do plano. # Atualizar um plano Source: https://docs.fastpaybrasil.com/referencia/planos/atualizar PUT /v1/subscription-plans/{id} Altera nome, preço, periodicidade, trial e outros dados de um plano. As mudanças valem só para novas assinaturas. Esta rota muda a configuração de um plano existente. Ela serve para reajustar o preço de venda, trocar o nome comercial, incluir ou remover um trial e mudar a mensagem ao comprador. Quem já assinou não é afetado: preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. ## Quando usar | Situação | Como usar esta rota | | - | - | | Reajuste de preço para novos clientes | Envie `merchantId` e o novo `price` | | Lançar ou encerrar uma promoção de trial | Envie `trial` com a nova configuração, ou `trial: null` para remover | | Renomear o plano | Envie `merchantId` e `name` | | Parar de vender o plano | Use [Alterar status do plano](/referencia/planos/alterar-status). O `status` não faz parte desta rota | | Trocar a imagem do plano | Use [Enviar imagem do plano](/referencia/planos/enviar-imagem) | | Reajustar o preço de quem já assina | Não é possível. A assinatura mantém as condições da contratação. Para mudar, cancele e crie outra assinatura | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **atualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Tenha o `id` do plano e o `merchantId` dono dele. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). > [!WARNING] > > Editar o plano **não** altera assinaturas existentes. Se você reduzir o preço, os assinantes atuais continuam pagando o valor antigo. Comunique isso ao seu time comercial e de atendimento antes de anunciar um novo preço. ## Parâmetros de caminho **id** `string` *required* Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Corpo da requisição Campo obrigatório: `merchantId`. Os demais são opcionais: envie os que quer alterar. **merchantId** `string` *required* ID do merchant dono do plano, usado na validação da requisição. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **name** `string` Nome do plano. Ex.: `Plano Premium Atualizado`. **price** `number` Novo preço do plano, em reais. Ex.: `119.9` (R\$ 119,90). **currency** `string` Código da moeda. Ex.: `BRL`. Planos cobrados no cartão aceitam apenas `BRL`. **recurrenceType** `string` Periodicidade: `weekly` (semanal), `biweekly` (quinzenal), `monthly` (mensal) ou `custom` (intervalo personalizado). **recurrenceInterval** `integer` Intervalo da recorrência personalizada, em dias corridos. Ex.: `90` (a cada 90 dias). Usado só quando `recurrenceType` é `custom`. Note que `custom` com `30` não é igual a `monthly`: o mensal mantém o dia do mês, e o `custom` só soma dias. **endDate** `string` Data de término do plano (formato `date`). Ex.: `2025-12-31`. **buyerMessage** `string` Mensagem exibida ao comprador. **paymentMethods** `string[]` Formas de pagamento aceitas. Ex.: `["credit_card"]`. **trial** `object | null` Configuração de trial para **novas** assinaturas. Envie `null` para remover o trial do plano. **propriedades** **durationDays** `integer` Duração do trial em dias. Mínimo `1`, máximo `365`. **isFree** `boolean` Se o trial é grátis. **price** `number` Valor cobrado durante o trial, em reais. Obrigatório quando `isFree` é `false`. > [!NOTE] > > Na criação do plano, `durationDays` e `isFree` são obrigatórios dentro de `trial`. No contrato desta rota, nenhum campo de `trial` é marcado como obrigatório. Para evitar ambiguidade, envie o objeto `trial` completo sempre que alterá-lo. ## Respostas A resposta `200` traz só o `id` do plano. Para ver o plano com as alterações, chame [Consultar plano](/referencia/planos/consultar). **id** `string` Identificador único do plano. | HTTP | Significado | Corpo | | - | - | - | | `200` | Plano atualizado | `{"id": "..."}` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão atualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Plano não encontrado | `{"statusCode": 404, "message": "Subscription plan not found"}` | > [!NOTE] > > **Para o negócio:** um reajuste feito aqui cria duas tabelas de preço convivendo: a dos assinantes antigos (preço da contratação) e a dos novos (preço atualizado). A Finvia não migra assinantes de preço. Se a sua estratégia exige que todos paguem o novo valor, o caminho é cancelar a assinatura antiga e criar uma nova, com cobrança imediata e um ciclo novo. ## Exemplos por caso de uso > [tab] Reajuste de preço > > ```json theme={null} > { > "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "price": 119.9 > } > ``` > [tab] Incluir trial grátis > > ```json theme={null} > { > "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "trial": { "durationDays": 7, "isFree": true } > } > ``` > [tab] Remover trial > > ```json theme={null} > { > "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "trial": null > } > ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` com "Subscription plan not found" | `id` errado ou de outra conta | Confira o `id` na [listagem de planos](/referencia/planos/listar) | | `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão atualizar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Assinantes antigos continuam com o preço anterior | Comportamento documentado: a edição vale só para novas assinaturas | Para migrar alguém, cancele e crie nova assinatura | | Requisição com `status` não desativa o plano | `status` não faz parte desta rota | Use [Alterar status do plano](/referencia/planos/alterar-status) | ```http REST (JSON) theme={null} PUT /v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Atualizado", "price": 119.9, "currency": "BRL" } ``` ```bash cURL theme={null} curl -X PUT "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Atualizado", "price": 119.9, "currency": "BRL" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q', { method: 'PUT', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ merchantId: '2RhQg9M7ZCg3X3nMb9W1kX8Q', name: 'Plano Premium Atualizado', price: 119.9, currency: 'BRL', }), }, ); const { id } = await response.json(); // Para conferir as alterações: GET /v1/subscription-plans/{id} ``` ```python Python theme={null} import os import requests payload = { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Atualizado", "price": 119.9, "currency": "BRL", } response = requests.request( "PUT", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2RhQg9M7ZCg3X3nMb9W1kX8Q', 'name' => 'Plano Premium Atualizado', 'price' => 119.9, 'currency' => 'BRL', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'PUT', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Atualizado", "price": 119.9, "currency": "BRL" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("PUT", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Atualizado", "price": 119.9, "currency": "BRL" } """; var request = new HttpRequestMessage(HttpMethod.Put, "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Atualizado", "price": 119.9, "currency": "BRL" }`) req, err := http.NewRequest("PUT", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Put.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "merchantId" => "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name" => "Plano Premium Atualizado", "price" => 119.9, "currency" => "BRL", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Subscription plan not found" } ``` ## Veja também > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Alterar status do plano](/referencia/planos/alterar-status) > > Ative ou desative o plano para novas assinaturas. # Confirmar desativação do plano Source: https://docs.fastpaybrasil.com/referencia/planos/confirmar-desativacao PATCH /v1/subscription-plans/{id}/status/confirm Segunda etapa da desativação: envia o token de confirmação e efetiva a desativação do plano. Esta rota conclui a desativação de um plano. Ela recebe o `confirmationToken` devolvido por [Alterar status do plano](/referencia/planos/alterar-status) e, se o token for válido, o plano passa a `inactive` e deixa de aceitar novas assinaturas. A confirmação vale para qualquer desativação, tenha o plano assinaturas ativas ou não. As duas etapas existem para evitar que um plano seja tirado de venda por engano. ## Quando usar | Situação | Como usar esta rota | | - | - | | Logo depois de pedir `status` `inactive` | Envie o `confirmationToken` recebido | | Tela de administração com botão "Desativar plano" | Mostre o `activeSubscriptionsCount` do plano ([Consultar plano](/referencia/planos/consultar)), peça a desativação e chame esta rota quando o usuário confirmar | | Reativar um plano | Não é necessário. A ativação é imediata em [Alterar status do plano](/referencia/planos/alterar-status) | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **atualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Tenha o `confirmationToken` devolvido por `PATCH /v1/subscription-plans/{id}/status` para o mesmo plano. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). > [!WARNING] > > O token de confirmação vale por **5 minutos** e é de **uso único**. Pedir a desativação de novo gera outro token e invalida o anterior. Com token vencido, já usado ou substituído, a chamada falha com `400` e é preciso pedir a desativação de novo. ## Parâmetros de caminho **id** `string` *required* Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Corpo da requisição **confirmationToken** `string` *required* Token recebido na rota de alteração de status. Ex.: `abc123xyz`. ## Respostas A resposta de sucesso não tem corpo. Para conferir o novo status, consulte o plano em [Consultar plano](/referencia/planos/consultar). | HTTP | Significado | Corpo | | - | - | - | | `204` | Desativação confirmada | Sem corpo | | `400` | Token inválido ou expirado | `{"statusCode": 400, "message": "Invalid or expired confirmation token"}` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão atualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Plano inexistente ou de outra conta | `{"statusCode": 404, "message": "Subscription plan not found"}` | > [!NOTE] > > **Para o negócio:** depois da confirmação, o plano some das opções de venda, mas as assinaturas existentes continuam ativas e renovando a cada ciclo. Desativar um plano não gera estorno nem cancelamento para ninguém. Para encerrar as assinaturas, é preciso cancelar uma a uma. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `400` "Invalid or expired confirmation token" | Token com mais de 5 minutos, já usado, substituído por um pedido mais recente, digitado errado ou de outro plano | Peça a desativação de novo em [Alterar status do plano](/referencia/planos/alterar-status) e confirme em seguida | | `404` "Subscription plan not found" | `id` do plano errado ou de outra conta | Confira o `id` na [listagem de planos](/referencia/planos/listar) | | `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão atualizar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Resposta vazia interpretada como erro | Sucesso devolve `204` sem corpo | Trate `204` como sucesso e não tente ler JSON da resposta | ```http REST (JSON) theme={null} PATCH /v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "confirmationToken": "abc123xyz" } ``` ```bash cURL theme={null} curl -X PATCH "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{"confirmationToken": "abc123xyz"}' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm', { method: 'PATCH', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ confirmationToken: 'abc123xyz' }), }, ); if (response.status === 400) { // token expirado: peça a desativação de novo } ``` ```python Python theme={null} import os import requests payload = { "confirmationToken": "abc123xyz", } response = requests.request( "PATCH", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'abc123xyz', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'PATCH', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "confirmationToken": "abc123xyz" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "confirmationToken": "abc123xyz" } """; var request = new HttpRequestMessage(HttpMethod.Patch, "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "confirmationToken": "abc123xyz" }`) req, err := http.NewRequest("PATCH", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status/confirm") request = Net::HTTP::Patch.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "confirmationToken" => "abc123xyz", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 204 theme={null} (sem corpo) ``` ```json 400 theme={null} { "statusCode": 400, "message": "Invalid or expired confirmation token" } ``` ## Veja também > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Alterar status do plano](/referencia/planos/alterar-status) > > Primeira etapa: peça a desativação e receba o token. # Consultar um plano Source: https://docs.fastpaybrasil.com/referencia/planos/consultar GET /v1/subscription-plans/{id} Devolve os dados de um plano de assinatura: preço, periodicidade, status e quantidade de assinaturas ativas. Esta rota traz a configuração atual de um plano a partir do `id`. Use-a para conferir se o plano está disponível antes de levar o cliente ao checkout e para exibir nome, preço e imagem do plano na sua aplicação. ## Quando usar | Situação | Como usar esta rota | | - | - | | Antes do checkout da assinatura | Confira se `status` é `active`. Plano inativo faz a criação da assinatura falhar com `404` | | Página de detalhes do plano | Exiba `name`, `price`, `buyerMessage` e `imageUrl` | | Conferir uma alteração feita em [Atualizar plano](/referencia/planos/atualizar) | Compare os campos e o `updatedAt` | | Ver todos os planos | Use [Listar planos](/referencia/planos/listar) | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **visualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager**, **Operador** e **Visualizador**. Os perfis Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Tenha o `id` do plano, devolvido na criação ou na listagem. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). ## Parâmetros de caminho **id** `string` *required* Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Respostas **id** `string` Identificador único do plano. **merchantId** `string` ID do merchant dono do plano. **name** `string` Nome do plano. Ex.: `Plano Premium Mensal`. **price** `number` Preço do plano, em reais: `99.9` significa R\$ 99,90. **currency** `string` Código da moeda. Ex.: `BRL`. **recurrenceType** `string` Periodicidade: `weekly` (semanal), `biweekly` (quinzenal), `monthly` (mensal) ou `custom` (intervalo personalizado). **recurrenceInterval** `integer | null` Intervalo da recorrência personalizada, em dias corridos (ex.: `90` = a cada 90 dias). `null` quando o plano não é `custom`. **endDate** `string | null` Data de término do plano (formato `date-time`). `null` quando não há data de término. **buyerMessage** `string | null` Mensagem exibida ao comprador. Ex.: `Bem-vindo ao Plano Premium!`. **paymentMethods** `string[]` Formas de pagamento aceitas. Ex.: `["credit_card"]`. **imageUrl** `string | null` URL da imagem do plano. **status** `string` Status do plano: `active` (aceita novas assinaturas) ou `inactive` (não aceita). **activeSubscriptionsCount** `integer` Quantidade de assinaturas ativas no plano. Ex.: `150`. **createdAt** `string` Data de criação (formato `date-time`). **updatedAt** `string` Data da última atualização (formato `date-time`). | HTTP | Significado | Corpo | | - | - | - | | `200` | Plano encontrado | Objeto do plano | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão visualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Plano não encontrado | `{"statusCode": 404, "message": "Subscription plan not found"}` | > [!NOTE] > > **Para o negócio:** os dados devolvidos aqui valem para **novas** assinaturas. Quem já assinou continua pagando o preço, a moeda e a periodicidade da data da contratação, mesmo que o plano tenha sido alterado depois. Para saber o que um assinante específico paga, consulte a assinatura em [Consultar assinatura](/referencia/assinaturas/consultar). ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` com "Subscription plan not found" | `id` errado ou de outra conta | Confira o `id` na [listagem de planos](/referencia/planos/listar) feita com a mesma chave | | `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão visualizar assinaturas (ex.: Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Checkout da assinatura falha mesmo com plano encontrado | Plano com `status` `inactive` | Reative em [Alterar status do plano](/referencia/planos/alterar-status) ou use outro plano | ```http REST (JSON) theme={null} GET /v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q', { headers: { Authorization: `Basic ${credentials}` } }, ); const plan = await response.json(); if (plan.status !== 'active') { // não leve o cliente ao checkout com um plano inativo } ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "recurrenceInterval": null, "endDate": null, "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": ["credit_card"], "imageUrl": "https://storage.example.com/plans/image.png", "status": "active", "activeSubscriptionsCount": 150, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Subscription plan not found" } ``` ## Veja também > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Atualizar plano](/referencia/planos/atualizar) > > Altere preço, nome ou trial para novas assinaturas. # Criar um plano Source: https://docs.fastpaybrasil.com/referencia/planos/criar POST /v1/subscription-plans Cadastra um plano de assinatura com preço, moeda, periodicidade e, se quiser, período de trial. O plano é o "produto" que o seu cliente assina: ele define **quanto** cobrar, **em que moeda** e **de quanto em quanto tempo**. Toda assinatura nasce a partir de um plano, então esta é a primeira rota que você chama ao montar uma oferta recorrente, como uma mensalidade de software, um clube de assinatura ou uma escola com cobrança mensal. ## Quando usar | Situação | Como usar esta rota | | - | - | | Mensalidade de software (SaaS) | `recurrenceType` `monthly` | | Clube com entrega semanal ou quinzenal | `recurrenceType` `weekly` ou `biweekly` | | Plano trimestral, semestral ou outro intervalo | `recurrenceType` `custom` com `recurrenceInterval` | | Oferta com degustação grátis ou paga | Objeto `trial` | | Campanha com data para acabar | `endDate` | | Mudar o preço de um plano existente | Use [Atualizar plano](/referencia/planos/atualizar). As assinaturas existentes mantêm o preço da contratação | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **criar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Tenha o `merchantId` da conta que vai vender o plano. * Defina a periodicidade e, se houver, as regras do trial. O preço e a periodicidade ficam congelados em cada assinatura no momento da contratação: editar o plano depois só vale para assinaturas novas. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste, inclusive a validação de R\$ 1,00 do trial grátis. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). > [!WARNING] > > O valor vai em **reais**: `"price": 99.9` significa R\$ 99,90. Planos cobrados no cartão aceitam apenas a moeda `BRL`. ## Corpo da requisição Campos obrigatórios: `merchantId`, `name`, `price`, `currency` e `recurrenceType`. **merchantId** `string` *required* ID do merchant que vai vender o plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **name** `string` *required* Nome do plano. Ex.: `Plano Premium Mensal`. **price** `number` *required* Preço cobrado a cada ciclo, na unidade da moeda (ex.: `99.90` = R\$ 99,90). **currency** `string` *required* Código da moeda no padrão ISO 4217. Ex.: `BRL`. Planos cobrados no cartão aceitam apenas `BRL`. **recurrenceType** `string` *required* Periodicidade da cobrança: | Valor | Cobrança | | - | - | | `weekly` | Semanal | | `biweekly` | Quinzenal | | `monthly` | Mensal | | `custom` | Intervalo personalizado, definido em `recurrenceInterval` | **recurrenceInterval** `integer` Intervalo da recorrência personalizada, **em dias corridos**. Inteiro maior que zero, obrigatório quando `recurrenceType` é `custom`. Ex.: `90` (cobrança a cada 90 dias). Nos tipos `weekly`, `biweekly` e `monthly`, o campo é ignorado. > [!WARNING] > > `custom` com `30` não é igual a `monthly`. O mensal mantém o dia do mês da contratação; o `custom` só soma dias, e a data da cobrança desliza conforme o calendário. Para cobrar todo mês no mesmo dia, use `monthly`. **endDate** `string` Data de término do plano, no padrão ISO 8601 (formato `date`). Ex.: `2025-12-31`. Quando o período seguinte de uma assinatura começaria depois dessa data, a assinatura é encerrada com status `expired`. **buyerMessage** `string` Mensagem exibida ao comprador. Ex.: `Bem-vindo ao Plano Premium!`. **paymentMethods** `string[]` Formas de pagamento aceitas. Ex.: `["credit_card"]`. **trial** `object` Período de trial (teste) opcional. Quando informado, os novos assinantes passam pelo trial antes do primeiro ciclo cobrado com o valor cheio. **propriedades** **durationDays** `integer` *required* Duração do trial em dias. Mínimo `1`, máximo `365`. Ex.: `14`. **isFree** `boolean` *required* `true` para trial grátis. `false` para trial pago, que exige `price`. **price** `number` Valor cobrado durante o trial, em reais. Obrigatório quando `isFree` é `false`. Ex.: `9.9`. **status** `string` (default: active) Status inicial do plano: `active` (aceita novas assinaturas) ou `inactive` (não aceita). ### Como o trial afeta a primeira cobrança | Configuração | O que acontece ao criar a assinatura | | - | - | | Sem `trial` | A primeira cobrança com o valor cheio é feita na criação da assinatura e valida o cartão | | Trial grátis (`isFree: true`) | Nada da mensalidade é cobrado no início. Para validar o cartão, a Finvia cobra R\$ 1,00 e estorna em seguida | | Trial pago (`isFree: false`) | O valor do trial é cobrado na criação da assinatura e valida o cartão | | Assinatura criada com `skipTrial: true` | O trial é ignorado e o valor cheio é cobrado na criação da assinatura | Ao fim do trial, a primeira cobrança cheia é processada no ciclo normal de cobrança. > [!NOTE] > > **Para o negócio:** no trial grátis, o comprador pode ver na fatura do cartão duas linhas de R\$ 1,00 (a cobrança de validação e o estorno, que é feito logo depois, de forma assíncrona). Avise o comprador disso no checkout. Se a validação for recusada, ficar em análise ou o processador não responder, a assinatura não é criada e a API responde `422 CARD_VALIDATION_FAILED`. ## Respostas A resposta `201` traz só o `id` do plano. Para ver o plano completo, chame [Consultar plano](/referencia/planos/consultar). **id** `string` Identificador único do plano. Guarde este valor: ele vai em `subscriptionPlanId` ao [criar a assinatura](/referencia/assinaturas/criar). | HTTP | Significado | Corpo | | - | - | - | | `201` | Plano criado | `{"id": "..."}` | | `400` | Método desconhecido em `paymentMethods` | `message` começando com `Invalid payment methods:` | | `400` | Erro de validação do corpo | `message` em lista | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão criar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | `merchantId` de uma conta a que a chave não tem acesso | `Merchant not found` | | `404` | Moeda inexistente em `currency` | `Currency not found` | ## Exemplos por caso de uso > [tab] Mensal (SaaS) > > Plano mensal de um software de gestão, sem trial. > > ```json theme={null} > { > "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "name": "Plano Profissional Mensal", > "price": 149.9, > "currency": "BRL", > "recurrenceType": "monthly", > "buyerMessage": "Obrigado por assinar o Plano Profissional!", > "paymentMethods": ["credit_card"] > } > ``` > [tab] Trial grátis de 14 dias > > O assinante usa 14 dias sem pagar a mensalidade. O cartão é validado com R\$ 1,00, estornado em seguida. > > ```json theme={null} > { > "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "name": "Plano Premium Mensal", > "price": 99.9, > "currency": "BRL", > "recurrenceType": "monthly", > "paymentMethods": ["credit_card"], > "trial": { "durationDays": 14, "isFree": true } > } > ``` > [tab] Trial pago > > Primeiro mês promocional a R\$ 9,90, depois R\$ 99,90 por mês. > > ```json theme={null} > { > "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "name": "Plano Premium Mensal", > "price": 99.9, > "currency": "BRL", > "recurrenceType": "monthly", > "paymentMethods": ["credit_card"], > "trial": { "durationDays": 30, "isFree": false, "price": 9.9 } > } > ``` > [tab] Personalizado com data de término > > Plano cobrado a cada 90 dias que deixa de renovar depois do fim do ano. > > ```json theme={null} > { > "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", > "name": "Mensalidade Curso Técnico", > "price": 350, > "currency": "BRL", > "recurrenceType": "custom", > "recurrenceInterval": 90, > "endDate": "2025-12-31", > "paymentMethods": ["credit_card"], > "status": "active" > } > ``` ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão criar assinaturas (ex.: perfil Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | `404` com `Merchant not found` | `merchantId` de outra conta, ou com erro de digitação | Use o id da conta dona da chave ou de uma subconta a que ela tem acesso | | `404` com `Currency not found` | Código de moeda inexistente | Envie um código ISO 4217 válido, como `BRL` | | `400` com `Invalid payment methods` | Método desconhecido em `paymentMethods` | Envie só métodos válidos, como `credit_card` | | `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` | | Plano com moeda diferente de `BRL` não serve para cartão | Planos cobrados no cartão aceitam só `BRL` | Use `currency` `BRL` | | Trial pago sem valor | `isFree: false` sem `trial.price` | Envie `trial.price` | | Data de cobrança "deslizando" no plano `custom` | O intervalo conta dias corridos | Use `monthly` se quiser cobrar todo mês | ```http REST (JSON) theme={null} POST /v1/subscription-plans HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card" ], "status": "active" } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Mensal", "price": 99.90, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": ["credit_card"], "status": "active" }' ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const response = await fetch('https://api-global.fastpaybrasil.com/v1/subscription-plans', { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ merchantId: '2RhQg9M7ZCg3X3nMb9W1kX8Q', name: 'Plano Premium Mensal', price: 99.9, currency: 'BRL', recurrenceType: 'monthly', buyerMessage: 'Bem-vindo ao Plano Premium!', paymentMethods: ['credit_card'], trial: { durationDays: 14, isFree: true }, }), }); const { id } = await response.json(); // Para ver o plano completo: GET /v1/subscription-plans/{id} ``` ```python Python theme={null} import os import requests payload = { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card", ], "status": "active", } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/subscription-plans", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2RhQg9M7ZCg3X3nMb9W1kX8Q', 'name' => 'Plano Premium Mensal', 'price' => 99.9, 'currency' => 'BRL', 'recurrenceType' => 'monthly', 'buyerMessage' => 'Bem-vindo ao Plano Premium!', 'paymentMethods' => [ 'credit_card', ], 'status' => 'active', ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscription-plans'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card" ], "status": "active" } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card" ], "status": "active" } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscription-plans"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": [ "credit_card" ], "status": "active" }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/subscription-plans", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "merchantId" => "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name" => "Plano Premium Mensal", "price" => 99.9, "currency" => "BRL", "recurrenceType" => "monthly", "buyerMessage" => "Bem-vindo ao Plano Premium!", "paymentMethods" => [ "credit_card", ], "status" => "active", }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 201 theme={null} { "id": "2RhQg9M7ZCg3X3nMb9W2kY9R" } ``` ```json 403 theme={null} { "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 } ``` ## Veja também > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Criar assinatura](/referencia/assinaturas/criar) > > Vincule um cliente ao plano e faça a primeira cobrança. # Enviar imagem do plano Source: https://docs.fastpaybrasil.com/referencia/planos/enviar-imagem POST /v1/subscription-plans/{id}/image Envia a imagem que representa o plano de assinatura, em PNG, JPG ou JPEG. Esta rota anexa uma imagem ao plano, como o logotipo do produto ou uma arte da oferta. Depois do envio, o endereço da imagem passa a aparecer no campo `imageUrl` do plano, pronto para ser exibido na sua vitrine de planos. ## Quando usar | Situação | Como usar esta rota | | - | - | | Plano recém-criado sem imagem | Chame logo depois de [Criar plano](/referencia/planos/criar), com o `id` devolvido | | Troca da arte de uma campanha | Envie o novo arquivo para o mesmo plano | | Ler a imagem atual | Use [Consultar plano](/referencia/planos/consultar) e leia `imageUrl` | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **atualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Tenha o `id` do plano. * Tenha o arquivo em PNG, JPG ou JPEG. > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). > [!TIP] > > **Para o desenvolvedor:** esta é uma das poucas rotas de assinatura que **não** recebem JSON. O corpo vai como `multipart/form-data`, com o arquivo no campo `file`. Não defina o header `Content-Type` manualmente ao usar `FormData` no Node.js ou a opção `-F` do cURL: a biblioteca monta o header com o `boundary` correto. ## Parâmetros de caminho **id** `string` *required* Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. ## Corpo da requisição Formato `multipart/form-data`. Campo obrigatório: `file`. **file** `file` *required* Arquivo de imagem (formato `binary`): PNG, JPG ou JPEG. ## Respostas A resposta de sucesso não tem corpo. Para obter a URL da imagem, consulte o plano e leia o campo `imageUrl`. | HTTP | Significado | Corpo | | - | - | - | | `204` | Imagem enviada | Sem corpo | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão atualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | | `404` | Plano não encontrado | `{"statusCode": 404, "message": "Subscription plan not found"}` | > [!NOTE] > > **Para o negócio:** a imagem é um dado do plano, guardado junto com nome, preço e mensagem ao comprador. A forma de exibi-la (tamanho, recorte, onde aparece) fica a cargo da sua aplicação, que lê o `imageUrl`. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` com "Subscription plan not found" | `id` errado ou de outra conta | Confira o `id` na [listagem de planos](/referencia/planos/listar) | | `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão atualizar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Requisição rejeitada ao enviar JSON ou Base64 | A rota espera `multipart/form-data` | Envie o arquivo no campo `file` de um formulário multipart | | Resposta vazia interpretada como erro | Sucesso devolve `204` sem corpo | Trate `204` como sucesso e não tente ler JSON da resposta | ```http REST (JSON) theme={null} POST /v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: multipart/form-data; boundary=----FinviaBoundary ------FinviaBoundary Content-Disposition: form-data; name="file"; filename="plano-premium.png" ------FinviaBoundary-- ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image" \ -u "$FINVIA_API_KEY:" \ -F "file=@./plano-premium.png" ``` ```javascript Node.js theme={null} import { readFile } from 'node:fs/promises'; const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const form = new FormData(); const image = await readFile('./plano-premium.png'); form.append('file', new Blob([image], { type: 'image/png' }), 'plano-premium.png'); const response = await fetch( 'https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image', { method: 'POST', headers: { Authorization: `Basic ${credentials}` }, body: form, }, ); if (response.status === 204) { // imagem enviada; consulte o plano para ler imageUrl } ``` ```python Python theme={null} import os import requests files = { "file": open("./plano-premium.png", "rb"), } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image", auth=(os.environ["FINVIA_API_KEY"], ""), files=files, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_POSTFIELDS => [ 'file' => new CURLFile('./plano-premium.png', null, 'plano-premium.png'), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String boundary = "FinviaBoundary"; ByteArrayOutputStream form = new ByteArrayOutputStream(); String[][] files = { {"file", "./plano-premium.png"}, }; for (String[] file : files) { Path path = Path.of(file[1]); form.write(("--" + boundary + "\r\n" + "Content-Disposition: form-data; name=\"" + file[0] + "\"; filename=\"" + path.getFileName() + "\"\r\n" + "Content-Type: application/octet-stream\r\n\r\n").getBytes()); form.write(Files.readAllBytes(path)); form.write("\r\n".getBytes()); } form.write(("--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); using var form = new MultipartFormDataContent(); form.Add(new ByteArrayContent(File.ReadAllBytes("./plano-premium.png")), "file", "plano-premium.png"); var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image"); request.Content = form; var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" "path/filepath" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) files := [][2]string{ {"file", "./plano-premium.png"}, } for _, file := range files { part, err := writer.CreateFormFile(file[0], filepath.Base(file[1])) if err != nil { panic(err) } content, err := os.ReadFile(file[1]) if err != nil { panic(err) } part.Write(content) } writer.Close() req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image", &form) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", writer.FormDataContentType()) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request.set_form( [ ["file", File.open("./plano-premium.png")], ], "multipart/form-data" ) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 204 theme={null} (sem corpo) ``` ```json 404 theme={null} { "statusCode": 404, "message": "Subscription plan not found" } ``` ## Veja também > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Fluxo completo, do cliente à cobrança recorrente. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Consultar plano](/referencia/planos/consultar) > > Leia o `imageUrl` atualizado. # Listar planos Source: https://docs.fastpaybrasil.com/referencia/planos/listar GET /v1/subscription-plans Lista os planos de assinatura da sua conta, com filtro por status e paginação. Esta rota devolve os planos de assinatura cadastrados, página por página. É a base para montar a vitrine de planos no seu site, conferir quais planos estão disponíveis para venda e acompanhar quantas assinaturas ativas cada um tem. ## Quando usar | Situação | Como usar esta rota | | - | - | | Montar a página de preços do seu produto | `status=active`, para mostrar só planos que aceitam novas assinaturas | | Revisar o catálogo antes de uma mudança de preço | Sem filtro de status, para ver ativos e inativos | | Acompanhar a base de assinantes por plano | Leia `activeSubscriptionsCount` de cada plano | | Ver apenas os planos de um merchant específico | Filtre por `merchantId` | | Detalhes de um plano específico | Use [Consultar plano](/referencia/planos/consultar) | ## Antes de chamar * Tenha uma chave secreta gerada por usuário com a permissão **visualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager**, **Operador** e **Visualizador**. Os perfis Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil)). * Saiba como funciona a paginação da API: o parâmetro de tamanho da página é `size` ([Paginação, ordenação e idempotência](/primeiros-passos/paginacao-ordenacao-idempotencia)). > [!WARNING] > > Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](/guias/assinaturas/visao-geral). ## Parâmetros de consulta **merchantId** `string` Filtra pelos planos de um merchant específico. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **status** `string` Filtra pelo status do plano: `active` (disponível para novas assinaturas) ou `inactive` (indisponível para novas assinaturas). **page** `integer` (default: 1) Número da página. A contagem começa em `1`. **size** `integer` (default: 10) Quantidade de planos por página. ## Respostas **data** `object[]` Planos da página atual. **propriedades** **id** `string` Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **merchantId** `string` ID do merchant dono do plano. **name** `string` Nome do plano. Ex.: `Plano Premium Mensal`. **price** `number` Preço do plano, em reais: `99.9` significa R\$ 99,90. **currency** `string` Código da moeda. Ex.: `BRL`. **recurrenceType** `string` Periodicidade da cobrança: `weekly` (semanal), `biweekly` (quinzenal), `monthly` (mensal) ou `custom` (intervalo personalizado). **recurrenceInterval** `integer | null` Intervalo da recorrência personalizada, em dias corridos (ex.: `90` = a cada 90 dias). Vem `null` quando o plano não é `custom`. **endDate** `string | null` Data de término do plano (formato `date-time`). Vem `null` quando o plano não tem data de término. **buyerMessage** `string | null` Mensagem exibida ao comprador. Ex.: `Bem-vindo ao Plano Premium!`. **paymentMethods** `string[]` Formas de pagamento aceitas. Ex.: `["credit_card"]`. **imageUrl** `string | null` URL da imagem do plano, enviada por [Enviar imagem do plano](/referencia/planos/enviar-imagem). **status** `string` Status do plano: `active` ou `inactive`. **activeSubscriptionsCount** `integer` Quantidade de assinaturas ativas no plano. Ex.: `150`. **createdAt** `string` Data de criação (formato `date-time`). **updatedAt** `string` Data da última atualização (formato `date-time`). **meta** `object` Dados da paginação. **propriedades** **total** `integer` Total de planos encontrados. Ex.: `5`. **page** `integer` Página atual. Ex.: `1`. **limit** `integer` Itens por página. Ex.: `10`. **totalPages** `integer` Total de páginas. Ex.: `1`. > [!NOTE] > > Na requisição o tamanho da página vai em `size`. Na resposta, o mesmo valor volta no campo `meta.limit`. | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista devolvida | `data` e `meta` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | O usuário que gerou a chave não tem a permissão visualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` | > [!NOTE] > > **Para o negócio:** `activeSubscriptionsCount` mostra quantos assinantes ativos cada plano tem no momento. Antes de desativar ou reprecificar um plano, consulte esse número para saber quantos clientes já estão nele. Mudanças de preço e desativação não alteram as assinaturas existentes, que continuam com as condições da contratação. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` (com os dois-pontos no final) | | `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão visualizar assinaturas (ex.: Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](/guias/assinaturas/visao-geral#permissões-por-perfil) | | Lista vem com 10 planos mesmo enviando `limit=50` | O parâmetro de tamanho é `size` | Envie `size=50` | | Plano recém-desativado não aparece na vitrine | Filtro `status=active` | Comportamento esperado: plano `inactive` não aceita novas assinaturas | ```http REST (JSON) theme={null} GET /v1/subscription-plans?status=active&page=1&size=10 HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const params = new URLSearchParams({ status: 'active', page: '1', size: '10' }); const response = await fetch(`https://api-global.fastpaybrasil.com/v1/subscription-plans?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); const { data, meta } = await response.json(); ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "data": [ { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "name": "Plano Premium Mensal", "price": 99.9, "currency": "BRL", "recurrenceType": "monthly", "recurrenceInterval": null, "endDate": null, "buyerMessage": "Bem-vindo ao Plano Premium!", "paymentMethods": ["credit_card"], "imageUrl": "https://storage.example.com/plans/image.png", "status": "active", "activeSubscriptionsCount": 150, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" } ], "meta": { "total": 5, "page": 1, "limit": 10, "totalPages": 1 } } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## Veja também > [card] [Visão geral de assinaturas](/guias/assinaturas/visao-geral) > > Como planos, clientes, cartões e assinaturas se encaixam. > [card] [Planos](/guias/assinaturas/planos) > > Recorrência, trial e status do plano. > [card] [Ciclo de vida](/guias/assinaturas/ciclo-de-vida) > > Status, renovação, retentativas e cancelamento. > [card] [Webhooks de assinatura](/guias/webhooks/assinatura) > > Eventos enviados a cada etapa da assinatura. > [card] [Registrar cartão](/referencia/cartoes/registrar) > > Guarde o cartão no cofre antes de criar a assinatura. > [card] [Criar plano](/referencia/planos/criar) > > Cadastre um novo plano de assinatura. # Solicitar saque Source: https://docs.fastpaybrasil.com/referencia/saques/criar POST /v1/payout-requests Solicita um saque (payout) do saldo disponível da sua própria conta, enviado por Pix para a chave CNPJ da empresa. Esta rota transfere dinheiro do saldo disponível da sua conta para a conta bancária da empresa. O saque é enviado por **Pix**, em reais, para a **chave Pix CNPJ** igual ao CNPJ cadastrado na sua conta. A solicitação nasce `pending` e depois é aprovada ou recusada. Vale para qualquer conta, com ou sem o Connect. Só os saques de subconta geram webhook, qualquer que seja a rota usada para criar. O saque da conta master ou de uma conta sem Connect não gera webhook. ## Quando usar | Situação | Como usar esta rota | | - | - | | Sacar o saldo da sua conta pelo seu sistema | Envie `merchantId` da sua conta, `amount`, `currency` `BRL` e `externalAccountDetails` com `type` `pix` | | Rotina de saque periódico | Consulte o saldo em [Listar carteiras](/referencia/carteiras/listar) e peça o saque do valor disponível | | Saque do saldo de uma subconta do Connect | Use [Criar saque da subconta](/referencia/fast-connect/criar-saque) | | Acompanhar o saque pedido | Use [Listar saques](/referencia/saques/listar). Esta rota não devolve o `id` | ## Antes de chamar * Use a chave secreta (`sk_`) em Basic ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * A chave age com as permissões do usuário que a gerou. A chave padrão da conta pertence ao proprietário e funciona aqui. Uma chave gerada por um usuário com o perfil **Desenvolvedor** recebe `403` `Acesso negado`. * Não existe saque no Modo Teste. Com a chave de teste (`sk_test_`), a resposta é `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. * A conta precisa estar ativa, com saques habilitados e com taxa de saque configurada. * Cadastre o CNPJ da sua conta como **chave Pix** em uma conta bancária da empresa. É para essa chave que o Pix vai, e não é possível escolher outra. * Confira o saldo disponível em [Listar carteiras](/referencia/carteiras/listar): o campo `isWithdrawalEnabled` mostra se o saque está liberado na moeda. > [!WARNING] > > O valor vai em **reais**: `"amount": 100` significa R\$ 100,00, e `100.50` significa R\$ 100,50. Enviar `10000` pensando em R\$ 100,00 pede um saque de R\$ 10.000,00. O valor bruto sai do saldo disponível já na criação da solicitação. ## Corpo da requisição **merchantId** `string` *required* ID da sua própria conta. A rota não aceita o `id` de outra conta. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. **amount** `number` *required* Valor do saque em reais, maior que zero. Aceita casas decimais (ex.: `100.50` = R\$ 100,50). Ex.: `100`. **currency** `string` *required* Moeda do saque, em código ISO 4217. Use `BRL`. Um código inválido devolve `400`; um código válido que não é aceito para saque devolve `422`. **externalAccountDetails** `object` *required* Forma de envio do saque. Envie `{ "type": "pix" }`, sem outros campos. **propriedades** **type** `string` *required* Use `pix`. O Pix vai para a chave CNPJ da sua conta. ## Respostas A resposta de sucesso é `201` **sem corpo**: a API não devolve o `id` do saque. Para obter o `id` e acompanhar o status, chame [Listar saques](/referencia/saques/listar) filtrando pelo `merchantId` da sua conta. A lista vem do mais recente para o mais antigo, então o saque que você acabou de pedir é o primeiro. | HTTP | Significado | Exemplo de corpo | | - | - | - | | `201` | Solicitação de saque criada | sem corpo | | `400` | Corpo inválido, com `message` em lista | `{"statusCode": 400, "message": ["..."], "error": "Bad Request"}` | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Chave de teste (`WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`) ou usuário sem permissão de saque (`Acesso negado`) | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` | | `404` | Conta não encontrada | `{"statusCode": 404, "message": "Merchant not found", "error": "Not Found"}` | | `422` | Regra de negócio impediu o saque (mensagens abaixo) | `{"statusCode": 422, "message": "...", "error": "Unprocessable Entity"}` | As mensagens vêm em inglês, com uma exceção em português. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição. ### Mensagens do `422` | `message` | Causa | Como resolver | | - | - | - | | `Insufficient balance. Required: X, Available: Y` | O saldo disponível é menor que `amount` | Consulte o saldo e peça um valor menor | | `Maximum withdrawal amount is X` | O valor passa do limite máximo por saque configurado para a sua conta | Divida em saques menores, um de cada vez | | `You already have a pending withdrawal request for this currency` | Já existe um saque `pending` nessa moeda | Aguarde a decisão do saque anterior | | `Withdrawals are disabled for this merchant` | Saques desabilitados para a conta | Fale com o suporte da Finvia | | `Saques estão desabilitados para esta conta (saldo retido por configuração administrativa)` | A conta está com saldo retido | Fale com o suporte da Finvia | | `Merchant account is not active` | A conta não está ativa | Fale com o suporte da Finvia | | `Merchant settings are not configured correctly` | Configuração da conta incompleta | Fale com o suporte da Finvia | | `Payout fees not configured` | Taxa de saque não configurada | Peça à Finvia a configuração da taxa de saque | | `Currency X is not supported for withdrawals` | Moeda não aceita para saque | Use `BRL` | | `You can only create withdrawal requests for your own account` | `merchantId` de outra conta | Envie o `id` da sua própria conta | | `Payout execution failed: ...` | Falha ao executar um saque com aprovação automática | Consulte a listagem antes de tentar de novo (veja abaixo) | > [!WARNING] > > Se receber `422` `Payout execution failed: ...`, **não repita o pedido de imediato**. A solicitação pode ter ficado criada como `pending`. Consulte [Listar saques](/referencia/saques/listar) e só peça de novo se o saque não aparecer. ## Regras do saque | Regra | Detalhe | | - | - | | Destino | Sempre Pix na chave CNPJ da própria conta (o mesmo CNPJ do cadastro) | | Saldo | O saldo disponível precisa ser maior ou igual a `amount`. O valor bruto sai do saldo disponível na criação | | Limite por saque | Há um limite máximo por saque configurado para a sua conta | | Saques pendentes | Por padrão, só um saque `pending` por moeda. A operação Finvia pode liberar mais de um para a conta | | Taxa | A taxa de saque da conta (fixa + percentual) é descontada: o valor transferido é `amount` menos a taxa | | Aprovação | O saque nasce `pending` e é aprovado ou recusado pela operação. A conta pode ter aprovação automática do Pix configurada | | Aviso | Só os saques de subconta geram webhook, qualquer que seja a rota usada para criar. O saque da conta master ou de conta sem Connect não gera webhook: acompanhe pela listagem | ### Status do saque | Status | O que significa | | - | - | | `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda decisão | | `approved` | Aprovado e enviado para pagamento. O Pix do valor líquido é enviado nesse momento | | `rejected` | Recusado. O valor volta ao saldo disponível | `approved` não confirma que o dinheiro já chegou à conta de destino. > [!NOTE] > > A API não consulta se o CNPJ está cadastrado como chave Pix. A solicitação é criada normalmente e o Pix é enviado na aprovação. Se a chave não existir, o Pix não é concluído, e o status do saque na API não mostra essa falha (ele pode continuar `pending` ou aparecer como `approved`). Nesse caso, fale com o suporte da Finvia. **Em validação (V-49):** o suporte está definindo o procedimento quando o Pix do saque falha (prazo e como o saldo volta). Enquanto isso, se o valor de um saque `approved` não chegar, abra um chamado com o `id` do saque. > [!NOTE] > > **Para o negócio:** antes do primeiro saque, a empresa precisa cadastrar o próprio CNPJ como chave Pix no banco. A taxa de saque é descontada do valor pedido. Transferência para conta bancária por outro meio e saque em outra moeda não fazem parte desta documentação. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chamada com chave de teste | Saques só existem em produção. Teste com um valor baixo em produção | | `403` `Acesso negado` | Chave gerada por usuário com perfil Desenvolvedor | Use a chave padrão da conta ou gere uma com usuário Owner ou Manager | | `400` com `message` em lista | Campo ausente ou inválido no corpo (ex.: sem `externalAccountDetails`) | Envie os quatro campos obrigatórios | | Não sei o `id` do saque | A resposta `201` não tem corpo | Liste com o `merchantId` da sua conta | | `422` `You already have a pending withdrawal request for this currency` | Saque anterior ainda pendente | Aguarde a decisão | | Saque `approved` e o dinheiro não chegou | O CNPJ não está cadastrado como chave Pix | Cadastre a chave e fale com o suporte | ```http REST (JSON) theme={null} POST /v1/payout-requests HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 100, "currency": "BRL", "externalAccountDetails": { "type": "pix" } } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/payout-requests" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 100, "currency": "BRL", "externalAccountDetails": { "type": "pix" } }' ``` ```javascript Node.js theme={null} const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const base = 'https://api-global.fastpaybrasil.com'; const merchantId = '2RhQg9M7ZCg3X3nMb9W1kX8Q'; const response = await fetch(`${base}/v1/payout-requests`, { method: 'POST', headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ merchantId, amount: 100, // R$ 100,00 currency: 'BRL', externalAccountDetails: { type: 'pix' }, }), }); if (response.status === 201) { // A resposta não tem corpo. Busque o saque mais recente da conta. const params = new URLSearchParams({ merchantId, page: '1', size: '1' }); const list = await fetch(`${base}/v1/payout-requests?${params}`, { headers: { Authorization: `Basic ${auth}` }, }).then((r) => r.json()); console.log('Saque criado:', list.data[0]?.id, list.data[0]?.status); } else { const error = await response.json(); console.error(response.status, error.message); } ``` ```python Python theme={null} import os import requests payload = { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 100, "currency": "BRL", "externalAccountDetails": { "type": "pix", }, } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/payout-requests", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} '2RhQg9M7ZCg3X3nMb9W1kX8Q', 'amount' => 100, 'currency' => 'BRL', 'externalAccountDetails' => [ 'type' => 'pix', ], ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/payout-requests'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 100, "currency": "BRL", "externalAccountDetails": { "type": "pix" } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payout-requests")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 100, "currency": "BRL", "externalAccountDetails": { "type": "pix" } } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/payout-requests"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount": 100, "currency": "BRL", "externalAccountDetails": { "type": "pix" } }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/payout-requests", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/payout-requests") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "merchantId" => "2RhQg9M7ZCg3X3nMb9W1kX8Q", "amount" => 100, "currency" => "BRL", "externalAccountDetails" => { "type" => "pix", }, }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 201 theme={null} (sem corpo) ``` ```json 403 theme={null} { "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" } ``` ```json 422 theme={null} { "statusCode": 422, "message": "You already have a pending withdrawal request for this currency", "error": "Unprocessable Entity" } ``` ## Veja também > [card] [Listar saques](/referencia/saques/listar) > > Obtenha o `id` e acompanhe o status. > [card] [Listar carteiras](/referencia/carteiras/listar) > > Saldo disponível antes do saque. > [card] [Saldos e meios de pagamento](/guias/saldos-e-meios-de-pagamento) > > Como saldo, saque e taxas se relacionam. > [card] [Criar saque da subconta](/referencia/fast-connect/criar-saque) > > Saque de subconta pela conta master. # Listar saques Source: https://docs.fastpaybrasil.com/referencia/saques/listar GET /v1/payout-requests Lista as solicitações de saque da sua conta e, para a conta master, também das subcontas, com filtros por conta, status, moeda e período. Esta rota lista as solicitações de saque (payouts) com filtros e paginação. É por ela que você acompanha um saque depois de criado: se está pendente, se foi aprovado ou recusado, quanto foi cobrado de taxa. A resposta também traz `pendingCount`, o total de saques pendentes que atendem aos filtros. ## Quando usar | Situação | Como usar esta rota | | - | - | | Descobrir o `id` de um saque que você acabou de pedir | `POST /v1/payout-requests` responde sem corpo. Liste com `merchantId` da sua conta: a lista vem do mais recente para o mais antigo | | Acompanhar um saque da conta master ou de conta sem Connect | Esse saque não gera webhook (só os saques de subconta geram, qualquer que seja a rota usada para criar). Consulte esta rota até o `status` mudar | | Fila de saques aguardando aprovação | Filtre por `status=pending` ou use `pendingCount` | | Extrato de saques de um vendedor (conta master) | Filtre por `merchantId` da subconta | | Conciliação mensal | Use `createdAtStart` e `createdAtEnd` | ## Antes de chamar * Use a chave secreta (`sk_`) em Basic, como no resto da API ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). * A chave age com as permissões do usuário que a gerou. A chave padrão da conta pertence ao proprietário e funciona aqui. Uma chave gerada por um usuário com o perfil **Desenvolvedor** recebe `403` `Acesso negado` nesta rota. * Com a chave de teste (`sk_test_`), a listagem só traz registros de teste. Como não existe saque no Modo Teste, na prática ela vem vazia. * Para filtrar por vendedor, tenha o `id` da subconta ([Listar subcontas](/referencia/fast-connect/listar-subcontas)). > [!NOTE] > > **Escopo da listagem:** a rota traz os saques de todas as contas a que a credencial tem acesso. Para a conta master do Connect, isso inclui os saques das subcontas. Para ver uma conta só, filtre por `merchantId`. ## Parâmetros de consulta Todos os parâmetros são opcionais. A lista vem sempre do saque mais recente para o mais antigo. **merchantId** `string` Filtra pela conta que pediu o saque (a sua própria conta ou uma subconta). Uma conta a que a credencial não tem acesso devolve `404` `Merchant not found`. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. **status** `string` Filtra pelo status da solicitação: `pending`, `approved` ou `rejected`. Ex.: `pending`. **currency** `string` Filtra pela moeda. Ex.: `BRL`. **createdAtStart** `string` Data inicial do filtro pela data de criação, no formato `AAAA-MM-DD`. A data é inclusiva. Ex.: `2026-10-01`. **createdAtEnd** `string` Data final do filtro pela data de criação, no formato `AAAA-MM-DD`. A data é inclusiva. Ex.: `2026-10-31`. **page** `integer` (default: 1) Número da página, começando em `1`. **size** `integer` (default: 10) Quantidade de itens por página. Ex.: `20`. > [!WARNING] > > A API ignora parâmetros desconhecidos sem devolver erro. Não existem filtros `createdAt` nem `processedAt`: enviados, eles não filtram nada e a lista volta completa. Use `createdAtStart` e `createdAtEnd`. ## Respostas **data** `object[]` Solicitações de saque da página atual. **propriedades** **id** `string` Identificador da solicitação de saque. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. **merchantId** `string` Conta que solicitou o saque. Pode ser a sua própria conta ou, para a conta master, uma subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. **amount** `string` Valor bruto pedido, em reais, como texto decimal com 8 casas. Ex.: `"100.00000000"`. **currency** `string` Moeda do saque. Ex.: `BRL`. **status** `string` Status atual: `pending`, `approved` ou `rejected`. **payoutFee** `string` Taxa de saque cobrada, em reais, como texto decimal com 8 casas. Ex.: `"1.00000000"`. **externalAccountDetails** `object` Destino do saque, com as chaves em snake\_case, como foram gravadas. **propriedades** **type** `string` Tipo do destino. Ex.: `pix`. **pix\_key** `string` Chave Pix de destino: o CNPJ cadastrado na conta que sacou. Ex.: `11222333000181`. **processedAt** `string | null` Data e hora da decisão (formato `date-time`). Preenchido quando o saque é aprovado ou recusado. **createdAt** `string` Data e hora de criação (formato `date-time`). Ex.: `2026-10-20T18:45:52.988Z`. **merchantLegalName** `string` Razão social da conta que solicitou o saque. Ex.: `LOJA EXEMPLO LTDA`. **merchantEmail** `string` E-mail de contato da conta que solicitou o saque. Ex.: `financeiro@lojaexemplo.com.br`. **total** `integer` Total de solicitações em todas as páginas. Ex.: `42`. **page** `integer` Página atual. Ex.: `1`. **size** `integer` Solicitações por página. Ex.: `20`. **pages** `integer` Total de páginas. Ex.: `3`. **pendingCount** `integer` Total de saques `pending` com os mesmos filtros da consulta, sem considerar o filtro `status`. Ex.: `3`. > [!NOTE] > > Os itens da listagem não trazem `netAmount`, `rejectionReason` nem `updatedAt`. O valor líquido é `amount` menos `payoutFee`. O motivo da recusa chega no webhook `payout.rejected` (saques de subconta) ou pelo suporte. > [!TIP] > > **Para o desenvolvedor:** `amount` e `payoutFee` chegam como texto (`"100.00000000"`). Converta antes de somar ou comparar, de preferência com uma biblioteca decimal ou em centavos: `Math.round(Number(item.amount) * 100)`. ### Status do saque | Status | O que significa | | - | - | | `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda decisão | | `approved` | Aprovado pela operação ou por aprovação automática e enviado para pagamento. `processedAt` é preenchido | | `rejected` | Recusado. O valor reservado volta ao saldo disponível e `processedAt` é preenchido | `approved` quer dizer aprovado e enviado para pagamento. Ele não confirma que o dinheiro já está na conta de destino. ### Códigos HTTP | HTTP | Significado | Exemplo de corpo | | - | - | - | | `200` | Lista devolvida | `data`, `total`, `page`, `size`, `pages`, `pendingCount` | | `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Usuário dono da chave sem permissão de saque (ex.: perfil Desenvolvedor) | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` | | `404` | `merchantId` de uma conta a que a credencial não tem acesso | `{"statusCode": 404, "message": "Merchant not found", "error": "Not Found"}` | Trate o erro pelo código HTTP, não pelo texto da mensagem. > [!NOTE] > > **Para o negócio:** com `merchantId` e o período, o time financeiro monta o extrato de saques de cada conta e confere a taxa cobrada (`payoutFee`). `pendingCount` mostra quantos saques ainda aguardam decisão sem precisar percorrer todas as páginas. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` `Acesso negado` | A chave foi gerada por um usuário com perfil Desenvolvedor | Use a chave padrão da conta ou gere uma com um usuário Owner ou Manager | | Lista vazia no Modo Teste | Não existe saque com chave de teste | Consulte com a chave de produção | | Filtro por data não muda o resultado | Foi usado `createdAt` ou `processedAt`, que não existem e são ignorados | Use `createdAtStart` e `createdAtEnd` no formato `AAAA-MM-DD` | | Conta master vê saques que não são dela | A listagem traz as contas a que a credencial tem acesso, inclusive subcontas | Filtre por `merchantId` | | Soma de valores errada no código | `amount` e `payoutFee` chegam como texto | Converta para número decimal antes de calcular | ```http REST (JSON) theme={null} GET /v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20 HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -G "https://api-global.fastpaybrasil.com/v1/payout-requests" \ -u "$FINVIA_API_KEY:" \ --data-urlencode "merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo" \ --data-urlencode "status=pending" \ --data-urlencode "createdAtStart=2026-10-01" \ --data-urlencode "createdAtEnd=2026-10-31" \ --data-urlencode "page=1" \ --data-urlencode "size=20" ``` ```javascript Node.js theme={null} const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const params = new URLSearchParams({ merchantId: '36OO3bcGjhPjjF3tzrqOGcmQuKo', status: 'pending', createdAtStart: '2026-10-01', createdAtEnd: '2026-10-31', page: '1', size: '20', }); const response = await fetch(`https://api-global.fastpaybrasil.com/v1/payout-requests?${params}`, { headers: { Authorization: `Basic ${auth}` }, }); const { data, pendingCount } = await response.json(); for (const saque of data) { const bruto = Number(saque.amount); const taxa = Number(saque.payoutFee); console.log(saque.id, saque.status, (bruto - taxa).toFixed(2)); } console.log(`${pendingCount} saques pendentes`); ``` ```python Python theme={null} import os import requests params = [ ("merchantId", "36OO3bcGjhPjjF3tzrqOGcmQuKo"), ("status", "pending"), ("createdAtStart", "2026-10-01"), ("createdAtEnd", "2026-10-31"), ("page", "1"), ("size", "20"), ] response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/payout-requests", auth=(os.environ["FINVIA_API_KEY"], ""), params=params, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&createdAtStart=2026-10-01&createdAtEnd=2026-10-31&page=1&size=20") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "data": [ { "id": "2vorkDcXyvzifL63YX09S9VqcnI", "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "amount": "100.00000000", "currency": "BRL", "status": "pending", "payoutFee": "1.00000000", "externalAccountDetails": { "type": "pix", "pix_key": "11222333000181" }, "processedAt": null, "createdAt": "2026-10-20T18:45:52.988Z", "merchantLegalName": "LOJA EXEMPLO LTDA", "merchantEmail": "financeiro@lojaexemplo.com.br" } ], "total": 1, "page": 1, "size": 20, "pages": 1, "pendingCount": 1 } ``` ```json 401 theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Merchant not found", "error": "Not Found" } ``` ## Veja também > [card] [Solicitar saque](/referencia/saques/criar) > > Saque do saldo da própria conta, por Pix. > [card] [Criar saque de subconta](/referencia/fast-connect/criar-saque) > > Saque da conta master para uma subconta. > [card] [Saques no Connect](/guias/fast-connect/saques) > > Fluxo, taxas e status dos saques. > [card] [Webhooks de saque](/guias/webhooks/saque) > > Avisos de aprovação e recusa dos saques de subconta. # Atualizar endpoint de webhook Source: https://docs.fastpaybrasil.com/referencia/webhooks/atualizar-endpoint PUT /v1/webhook-endpoints/{webhookId} Altera a URL, os eventos habilitados ou a opção de incluir subcontas de um endpoint de webhook. Esta rota altera um endpoint de webhook já cadastrado. Use-a para trocar a URL de recebimento (por exemplo, numa migração de servidor), ajustar a lista de eventos ou ligar e desligar o recebimento dos eventos das subcontas. ## Quando usar | Situação | O que enviar | | - | - | | Trocar o servidor que recebe os eventos | `url` | | Passar a receber todos os eventos | `enabled_events: []` | | Restringir aos eventos que a sua aplicação trata | `enabled_events` com a lista desejada | | Conta master que quer, ou não quer mais, os eventos das subcontas | `include_submerchants` | ## Antes de chamar * Use a chave secreta (`sk_`) em Basic ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). A chave age com as permissões do usuário que a gerou: um perfil sem permissão de webhooks recebe `403` `Acesso negado`. * Tenha o `id` do endpoint, obtido em [`GET /v1/webhook-endpoints`](/referencia/webhooks/listar-endpoints). * O corpo usa **snake\_case**, como na criação. ## Parâmetros de caminho **webhookId** `string` *required* Id do endpoint, o campo `id` da listagem. Ex.: `2wHn5Qe8rT1yU4iO7pA3sD6fG9k`. ## Corpo da requisição Todos os campos são opcionais. Envie os que você quer alterar. **url** `string` Novo endereço `http` ou `https` público. Endereços internos e reservados são recusados. Ex.: `https://api.meusite.com.br/webhooks/finvia`. **enabled\_events** `string[]` Lista de eventos que o endpoint recebe. Lista vazia (`[]`) recebe todos. Os nomes possíveis estão em [Criar endpoint](/referencia/webhooks/criar-endpoint). Incluir `charge.updated` não tem efeito: ele só vai ao `postbackUrl` da cobrança. **include\_submerchants** `boolean` Só para conta master com Connect habilitado. Com `true`, o endpoint recebe também os eventos das subcontas; com `false`, deixa de receber. ## Respostas A resposta de sucesso é `200` **sem corpo**. Para conferir o resultado, use [`GET /v1/webhook-endpoints`](/referencia/webhooks/listar-endpoints). | HTTP | Significado | Corpo | | - | - | - | | `200` | Endpoint atualizado | Sem corpo | | `400` | URL inválida, endereço reservado, `include_submerchants` em conta sem Connect ou corpo inválido | `{ statusCode, message, error }`. Nos erros de validação do corpo, `message` é uma lista | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Endpoint de conta sem acesso ou perfil de usuário sem permissão de webhooks | `{ statusCode, message, error }` | | `404` | Endpoint não encontrado | `{ statusCode, message, error }` | Mensagens literais da API (trate o erro pelo código HTTP, não pelo texto): | HTTP | `message` | Causa | | - | - | - | | `400` | `URL inválida: informe um endereço http(s) público (endereços internos e reservados não são permitidos)` | URL fora do formato ou apontando para endereço interno. Quando vem da validação do corpo, chega dentro de uma lista | | `400` | `Este endereço é reservado e não pode ser usado como destino.` | A URL aponta para um endereço reservado da plataforma | | `400` | `Apenas contas master com FastConnect habilitado podem receber eventos das subcontas` | `include_submerchants: true` em conta sem Connect | | `403` | `Acesso negado` | Conta a que a credencial não tem acesso, ou perfil de usuário sem permissão de webhooks | | `404` | `Webhook não encontrado` | `webhookId` inexistente | ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `Webhook não encontrado` | Id errado ou endpoint já excluído | Liste os endpoints e use o `id` atual | | Eventos de subconta continuam chegando | O mesmo endereço também está cadastrado direto na subconta | Liste os endpoints da subconta e exclua o cadastro duplicado | | `400` com "FastConnect habilitado" | `include_submerchants: true` em conta sem Connect | Retire o campo | ```http REST (JSON) theme={null} PUT /v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "url": "https://api.meusite.com.br/webhooks/finvia", "enabled_events": [] } ``` ```bash cURL theme={null} curl -X PUT "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.meusite.com.br/webhooks/finvia", "enabled_events": [] }' ``` ```javascript Node.js theme={null} // atualizar-endpoint.mjs (Node.js 18+, ESM, await no topo) const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const webhookId = '2wHn5Qe8rT1yU4iO7pA3sD6fG9k'; const response = await fetch(`https://api-global.fastpaybrasil.com/v1/webhook-endpoints/${webhookId}`, { method: 'PUT', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ url: 'https://api.meusite.com.br/webhooks/finvia', enabled_events: [], // todos os eventos }), }); if (response.status !== 200) { throw new Error(`Falha ao atualizar: ${response.status} ${await response.text()}`); } console.log('Endpoint atualizado'); ``` ```python Python theme={null} import os import requests payload = { "url": "https://api.meusite.com.br/webhooks/finvia", "enabled_events": [], } response = requests.request( "PUT", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'https://api.meusite.com.br/webhooks/finvia', 'enabled_events' => [], ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'PUT', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "url": "https://api.meusite.com.br/webhooks/finvia", "enabled_events": [] } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("PUT", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "url": "https://api.meusite.com.br/webhooks/finvia", "enabled_events": [] } """; var request = new HttpRequestMessage(HttpMethod.Put, "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "url": "https://api.meusite.com.br/webhooks/finvia", "enabled_events": [] }`) req, err := http.NewRequest("PUT", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k") request = Net::HTTP::Put.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "url" => "https://api.meusite.com.br/webhooks/finvia", "enabled_events" => [], }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 200 theme={null} (sem corpo) ``` ```json 404 theme={null} { "statusCode": 404, "message": "Webhook não encontrado", "error": "Not Found" } ``` ## Veja também > [card] [Listar endpoints](/referencia/webhooks/listar-endpoints) > > Obtenha o id e confira o resultado. > [card] [Excluir endpoint](/referencia/webhooks/excluir-endpoint) > > Pare de enviar eventos para uma URL. > [card] [Criar endpoint](/referencia/webhooks/criar-endpoint) > > Nomes de eventos e regras do cadastro. > [card] [Webhooks: visão geral](/guias/webhooks/visao-geral) > > Quem recebe cada evento e em que formato. # Criar endpoint de webhook Source: https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint POST /v1/webhook-endpoints Cadastra um endereço do seu servidor para receber os eventos de cobrança, assinatura e saque de uma conta, com filtro de eventos e a opção de incluir as subcontas. Esta rota cadastra um endpoint de webhook: a URL do seu servidor que vai receber, por `POST`, os eventos de cobrança, de assinatura e de saque de uma conta. Pela API, você escolhe quais eventos o endpoint recebe. Na conta master do Connect, um único endpoint pode receber também os eventos de todas as subcontas. ## Quando usar | Situação | Como usar esta rota | | - | - | | Receber os eventos da sua conta | `merchantId` com o id da sua conta e `enabled_events: []` para receber todos | | Receber só alguns eventos | Liste os eventos em `enabled_events`, por exemplo `["charge.paid", "charge.refunded"]` | | Conta master que quer os eventos de todas as subcontas | Endpoint na master com `include_submerchants: true` | | Endpoint próprio de uma subconta | A master usa a própria chave secreta com `merchantId` igual ao id da subconta | | Cadastro sem código | Use o painel, em **Configurações** > **Webhooks**. O endpoint cadastrado pelo painel recebe todos os eventos | ## Antes de chamar * Use a chave secreta (`sk_`) em Basic ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). A chave age com as permissões do usuário que a gerou: um perfil sem permissão de webhooks recebe `403` `Acesso negado`. * Tenha o id da conta que vai receber os eventos. Para uma subconta, consulte [Listar subcontas](/referencia/fast-connect/listar-subcontas). * A URL precisa ser um endereço `http` ou `https` público. Endereços internos e reservados são recusados. Use HTTPS. * O mesmo endpoint recebe eventos de teste e de produção. Veja [Teste e produção](/guias/webhooks/visao-geral#teste-e-produção). > [!WARNING] > > O corpo desta rota usa **snake\_case** (`enabled_events`, `include_submerchants`), diferente do resto da API. Os nomes em camelCase (`enabledEvents`) não são reconhecidos no corpo, embora a listagem devolva os campos em camelCase. ## Parâmetros de consulta **merchantId** `string` *required* Id da conta dona do endpoint: a sua própria conta ou, para a conta master, uma das subcontas que ela criou. Obrigatório para credenciais de conta: sem ele, a resposta é `403`. Ex.: `3Fq9TzL2mWc8VbN1xR7pK4hJ6sD`. ## Corpo da requisição **url** `string` *required* Endereço `http` ou `https` público que vai receber os eventos. Ex.: `https://meusite.com.br/webhooks/finvia`. **enabled\_events** `string[]` *required* Lista de eventos que o endpoint recebe. Lista vazia (`[]`) recebe todos. Nomes possíveis: * Cobrança: `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback`, `charge.blocked`. * Assinatura: `subscription.created`, `subscription.activated`, `subscription.renewed`, `subscription.payment_failed`, `subscription.cancelled`, `subscription.expired`. * Saque: `payout.approved`, `payout.rejected`. O `charge.updated` é entregue só ao `postbackUrl` da cobrança. Incluí-lo aqui não tem efeito. **include\_submerchants** `boolean` Só para conta master com Connect habilitado. Com `true`, o endpoint passa a receber também os eventos de cobrança, assinatura e saque das subcontas. O `merchant_id` (ou `merchantId`) de cada payload indica a subconta de origem. Em conta sem Connect, a resposta é `400`. ## Respostas A resposta de sucesso é `201` **sem corpo**: a API não devolve o id do endpoint. Para obter o id (necessário para editar ou excluir), use [`GET /v1/webhook-endpoints`](/referencia/webhooks/listar-endpoints) com o mesmo `merchantId`. | HTTP | Significado | Corpo | | - | - | - | | `201` | Endpoint criado | Sem corpo | | `400` | URL inválida, endereço reservado, `include_submerchants` em conta sem Connect ou corpo inválido | `{ statusCode, message, error }`. Nos erros de validação do corpo, `message` é uma lista | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Chamada sem `merchantId`, conta sem acesso ou perfil de usuário sem permissão de webhooks | `{ statusCode, message, error }` | | `404` | Conta não encontrada | `{ statusCode, message, error }` | Mensagens literais da API. Elas misturam português e inglês e podem mudar: trate o erro pelo código HTTP, não pelo texto. | HTTP | `message` | Causa | | - | - | - | | `400` | `URL inválida: informe um endereço http(s) público (endereços internos e reservados não são permitidos)` | URL fora do formato ou apontando para endereço interno. Quando vem da validação do corpo, chega dentro de uma lista | | `400` | `Este endereço é reservado e não pode ser usado como destino.` | A URL aponta para um endereço reservado da plataforma | | `400` | `Apenas contas master com FastConnect habilitado podem receber eventos das subcontas` | `include_submerchants: true` em conta sem Connect | | `400` | Lista com a descrição do campo inválido | Corpo inválido, por exemplo `enabled_events` que não é lista | | `403` | `Apenas administradores do gateway podem configurar endpoints de nível gateway` | Chamada sem `merchantId` | | `403` | `Acesso negado` | Conta a que a credencial não tem acesso, ou perfil de usuário sem permissão de webhooks | | `404` | `Merchant não encontrado` | `merchantId` inexistente | ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` com "administradores do gateway" | Faltou `merchantId` na query | Envie `?merchantId=` com o id da conta | | `400` de validação ao enviar `enabledEvents` | O campo obrigatório é `enabled_events`, em snake\_case | Envie `enabled_events` (use `[]` para todos os eventos) | | `400` com "FastConnect habilitado" | `include_submerchants` em conta sem Connect | Retire o campo ou peça a habilitação do Connect | | `400` com "URL inválida" | URL local (`localhost`), IP interno ou sem `http(s)` | Use uma URL pública. Em desenvolvimento, exponha a porta local com um túnel como o ngrok | | Não sei o id do endpoint criado | A resposta `201` não tem corpo | Liste com [`GET /v1/webhook-endpoints`](/referencia/webhooks/listar-endpoints) | | Eventos chegando duas vezes | Dois endpoints com a mesma URL, ou a mesma URL também usada como `postbackUrl` | Mantenha um cadastro por URL e deduplique os eventos | ```http REST (JSON) theme={null} POST /v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic Content-Type: application/json { "url": "https://meusite.com.br/webhooks/finvia", "enabled_events": [ "charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected" ], "include_submerchants": true } ``` ```bash cURL theme={null} curl -X POST "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD" \ -u "$FINVIA_API_KEY:" \ -H "Content-Type: application/json" \ -d '{ "url": "https://meusite.com.br/webhooks/finvia", "enabled_events": ["charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected"], "include_submerchants": true }' ``` ```javascript Node.js theme={null} // criar-endpoint.mjs (Node.js 18+, ESM, await no topo) const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const merchantId = '3Fq9TzL2mWc8VbN1xR7pK4hJ6sD'; const response = await fetch(`https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=${merchantId}`, { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ url: 'https://meusite.com.br/webhooks/finvia', enabled_events: [], // lista vazia: todos os eventos }), }); if (response.status !== 201) { throw new Error(`Falha ao criar endpoint: ${response.status} ${await response.text()}`); } console.log('Endpoint criado'); ``` ```python Python theme={null} import os import requests payload = { "url": "https://meusite.com.br/webhooks/finvia", "enabled_events": [ "charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected", ], "include_submerchants": True, } response = requests.request( "POST", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", auth=(os.environ["FINVIA_API_KEY"], ""), json=payload, timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'https://meusite.com.br/webhooks/finvia', 'enabled_events' => [ 'charge.paid', 'charge.refunded', 'charge.blocked', 'payout.approved', 'payout.rejected', ], 'include_submerchants' => true, ]; $ch = curl_init('https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); String payload = """ { "url": "https://meusite.com.br/webhooks/finvia", "enabled_events": [ "charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected" ], "include_submerchants": true } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD")) .header("Authorization", "Basic " + credentials) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var payload = """ { "url": "https://meusite.com.br/webhooks/finvia", "enabled_events": [ "charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected" ], "include_submerchants": true } """; var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD"); request.Content = new StringContent(payload, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "url": "https://meusite.com.br/webhooks/finvia", "enabled_events": [ "charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected" ], "include_submerchants": true }`) req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", payload) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "json" require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD") request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") request["Content-Type"] = "application/json" request.body = JSON.generate({ "url" => "https://meusite.com.br/webhooks/finvia", "enabled_events" => [ "charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected", ], "include_submerchants" => true, }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 201 theme={null} (sem corpo) ``` ```json 400 URL inválida theme={null} { "statusCode": 400, "message": [ "URL inválida: informe um endereço http(s) público (endereços internos e reservados não são permitidos)" ], "error": "Bad Request" } ``` ```json 400 Sem Connect theme={null} { "statusCode": 400, "message": "Apenas contas master com FastConnect habilitado podem receber eventos das subcontas", "error": "Bad Request" } ``` ```json 403 Sem merchantId theme={null} { "statusCode": 403, "message": "Apenas administradores do gateway podem configurar endpoints de nível gateway", "error": "Forbidden" } ``` ```json 404 theme={null} { "statusCode": 404, "message": "Merchant não encontrado", "error": "Not Found" } ``` ## Veja também > [card] [Listar endpoints](/referencia/webhooks/listar-endpoints) > > Obtenha o id e confira os eventos de cada endpoint. > [card] [Atualizar endpoint](/referencia/webhooks/atualizar-endpoint) > > Troque a URL ou os eventos. > [card] [Webhooks: visão geral](/guias/webhooks/visao-geral) > > Quem recebe cada evento, formatos e deduplicação. > [card] [Catálogo de eventos](/anexos/catalogo-de-eventos) > > Todos os eventos e quando são enviados. # Excluir endpoint de webhook Source: https://docs.fastpaybrasil.com/referencia/webhooks/excluir-endpoint DELETE /v1/webhook-endpoints/{webhookId} Remove um endpoint de webhook, e a URL deixa de receber os eventos da conta. Esta rota exclui um endpoint de webhook. Depois da exclusão, a URL deixa de receber os eventos de cobrança, assinatura e saque daquela conta. Não existe opção de desativar um endpoint temporariamente: para parar de receber, exclua; para voltar a receber, cadastre de novo. ## Quando usar | Situação | Como usar esta rota | | - | - | | Desligar um servidor antigo depois de uma migração | Cadastre o novo endpoint, confirme o recebimento e exclua o antigo | | Remover um cadastro duplicado (mesma URL em dois endpoints) | Exclua um deles | | A master passou a usar `include_submerchants` e não precisa mais dos endpoints de cada subconta | Exclua os endpoints das subcontas | > [!WARNING] > > Eventos enviados depois da exclusão não chegam a essa URL. Antes de excluir o único endpoint de uma conta, garanta que outro destino está recebendo os eventos, ou que a sua aplicação vai acompanhar as cobranças pela API. ## Antes de chamar * Use a chave secreta (`sk_`) em Basic ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). A chave age com as permissões do usuário que a gerou: um perfil sem permissão de webhooks recebe `403` `Acesso negado`. * Tenha o `id` do endpoint, obtido em [`GET /v1/webhook-endpoints`](/referencia/webhooks/listar-endpoints). ## Parâmetros de caminho **webhookId** `string` *required* Id do endpoint, o campo `id` da listagem. Ex.: `2wHn5Qe8rT1yU4iO7pA3sD6fG9k`. ## Respostas A resposta de sucesso é `200` **sem corpo**. | HTTP | Significado | Corpo | | - | - | - | | `200` | Endpoint excluído | Sem corpo | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Endpoint de conta sem acesso ou perfil de usuário sem permissão de webhooks | `{ statusCode, message, error }` com `message` `Acesso negado` | | `404` | Endpoint não encontrado | `{ statusCode, message, error }` com `message` `Webhook não encontrado` | Trate o erro pelo código HTTP, não pelo texto da mensagem. ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `404` `Webhook não encontrado` | Id errado ou endpoint já excluído | Liste os endpoints e confira o `id` | | `403` `Acesso negado` | O endpoint é de uma conta a que a credencial não tem acesso, ou o perfil do usuário não tem permissão de webhooks | Use uma chave da conta dona do endpoint (ou da master que criou a subconta) gerada por um usuário com permissão | | Eventos continuam chegando na URL | Outro endpoint com a mesma URL, endpoint da master com `include_submerchants: true` ou a URL também usada como `postbackUrl` das cobranças | Liste os endpoints da conta e da master e revise o `postbackUrl` enviado nas cobranças | ```http REST (JSON) theme={null} DELETE /v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X DELETE "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} // excluir-endpoint.mjs (Node.js 18+, ESM, await no topo) const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const webhookId = '2wHn5Qe8rT1yU4iO7pA3sD6fG9k'; const response = await fetch(`https://api-global.fastpaybrasil.com/v1/webhook-endpoints/${webhookId}`, { method: 'DELETE', headers: { Authorization: `Basic ${credentials}` }, }); if (response.status !== 200) { throw new Error(`Falha ao excluir: ${response.status} ${await response.text()}`); } console.log('Endpoint excluído'); ``` ```python Python theme={null} import os import requests response = requests.request( "DELETE", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'DELETE', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k")) .header("Authorization", "Basic " + credentials) .method("DELETE", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Delete, "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("DELETE", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/webhook-endpoints/2wHn5Qe8rT1yU4iO7pA3sD6fG9k") request = Net::HTTP::Delete.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```text 200 theme={null} (sem corpo) ``` ```json 404 theme={null} { "statusCode": 404, "message": "Webhook não encontrado", "error": "Not Found" } ``` ## Veja também > [card] [Listar endpoints](/referencia/webhooks/listar-endpoints) > > Obtenha o id do endpoint. > [card] [Criar endpoint](/referencia/webhooks/criar-endpoint) > > Cadastre um novo destino. > [card] [Atualizar endpoint](/referencia/webhooks/atualizar-endpoint) > > Troque a URL sem excluir. > [card] [Webhooks: visão geral](/guias/webhooks/visao-geral) > > Destinos, formatos e deduplicação. # Listar endpoints de webhook Source: https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints GET /v1/webhook-endpoints Lista os endpoints de webhook de uma conta, com a URL, os eventos habilitados e a opção de incluir subcontas de cada um. Esta rota lista os endpoints de webhook cadastrados em uma conta, pelo painel ou pela API. É por ela que você descobre o `id` de um endpoint, necessário para editar ou excluir, e confere quais eventos cada um recebe. ## Quando usar | Situação | Como usar esta rota | | - | - | | Descobrir o `id` do endpoint que você acabou de criar | `POST /v1/webhook-endpoints` responde sem corpo. Liste com o mesmo `merchantId` | | Auditar quais URLs recebem os eventos da conta | Liste e confira `url`, `enabledEvents` e `includeSubmerchants` | | Conferir os endpoints de uma subconta (conta master) | Use `merchantId` igual ao id da subconta | | Achar um endpoint específico | Use `search` | ## Antes de chamar * Use a chave secreta (`sk_`) em Basic ([Credenciais e ambientes](/primeiros-passos/credenciais-e-ambientes)). A chave age com as permissões do usuário que a gerou: um perfil sem permissão de webhooks recebe `403` `Acesso negado`. * Tenha o id da conta: a sua própria ou, para a conta master, o de uma subconta que ela criou. ## Parâmetros de consulta **merchantId** `string` *required* Id da conta cujos endpoints serão listados. Obrigatório para credenciais de conta: sem ele, a resposta é `403`. Ex.: `3Fq9TzL2mWc8VbN1xR7pK4hJ6sD`. **search** `string` Termo de busca. Ex.: `meusite`. **page** `integer` Número da página, começando em `1`. **size** `integer` Quantidade de itens por página. Ex.: `20`. ## Respostas A resposta `200` traz a página de endpoints e os totais. Diferente do corpo da criação, os itens vêm em **camelCase**. **data** `object[]` *required* Endpoints da página. **propriedades** **id** `string` Id do endpoint. É o `webhookId` usado para atualizar e excluir. **url** `string` URL que recebe os eventos. **merchantId** `string` Conta dona do endpoint. **enabledEvents** `string[]` Eventos habilitados. Lista vazia significa todos. **includeSubmerchants** `boolean` `true` se o endpoint também recebe os eventos das subcontas. **gatewayId** `string` Identificador do gateway ao qual a conta pertence. **createdAt** `string` Data e hora de criação (ISO 8601). **updatedAt** `string` Data e hora da última alteração (ISO 8601). **deletedAt** `string | null` Data e hora de exclusão, quando houver. **total** `integer` *required* Total de endpoints que atendem aos filtros, somando todas as páginas. **page** `integer` *required* Página devolvida. **size** `integer` *required* Itens por página. **pages** `integer` *required* Total de páginas. | HTTP | Significado | Corpo | | - | - | - | | `200` | Lista devolvida | `{ data, total, page, size, pages }` | | `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` | | `403` | Chamada sem `merchantId`, conta sem acesso ou perfil de usuário sem permissão de webhooks | `{ statusCode, message, error }` | | `404` | Conta não encontrada | `{ statusCode, message, error }` | Mensagens literais da API (trate o erro pelo código HTTP, não pelo texto): | HTTP | `message` | Causa | | - | - | - | | `403` | `Apenas administradores do gateway podem configurar endpoints de nível gateway` | Chamada sem `merchantId` | | `403` | `Acesso negado` | Conta a que a credencial não tem acesso, ou perfil de usuário sem permissão de webhooks | | `404` | `Merchant não encontrado` | `merchantId` inexistente | ## Erros comuns | Sintoma | Causa | Como resolver | | - | - | - | | `403` com "administradores do gateway" | Faltou `merchantId` na query | Envie `?merchantId=` com o id da conta | | Lista vazia na subconta, mas a master recebe os eventos | O endpoint está cadastrado na master, com `includeSubmerchants: true` | Liste com o `merchantId` da master | | Código lendo `enabled_events` na resposta | A resposta usa camelCase | Leia `enabledEvents` e `includeSubmerchants` | ```http REST (JSON) theme={null} GET /v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20 HTTP/1.1 Host: api-global.fastpaybrasil.com Authorization: Basic ``` ```bash cURL theme={null} curl -X GET "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20" \ -u "$FINVIA_API_KEY:" ``` ```javascript Node.js theme={null} // listar-endpoints.mjs (Node.js 18+, ESM, await no topo) const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'); const params = new URLSearchParams({ merchantId: '3Fq9TzL2mWc8VbN1xR7pK4hJ6sD', page: '1', size: '20' }); const response = await fetch(`https://api-global.fastpaybrasil.com/v1/webhook-endpoints?${params}`, { headers: { Authorization: `Basic ${credentials}` }, }); const { data, total } = await response.json(); console.log(`${total} endpoint(s)`); for (const endpoint of data) { console.log(endpoint.id, endpoint.url, endpoint.enabledEvents, endpoint.includeSubmerchants); } ``` ```python Python theme={null} import os import requests response = requests.request( "GET", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20", auth=(os.environ["FINVIA_API_KEY"], ""), timeout=30, ) print(response.status_code) if response.content: print(response.json()) ``` ```php PHP theme={null} 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':', ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, PHP_EOL; print_r(json_decode($body, true)); ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.Base64; public class Exemplo { public static void main(String[] args) throws Exception { String credentials = Base64.getEncoder() .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes()); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20")) .header("Authorization", "Basic " + credentials) .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); } } ``` ```csharp C# theme={null} using System.Net.Http.Headers; using System.Text; var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY"); var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:")); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials); var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```go Go theme={null} package main import ( "fmt" "io" "net/http" "os" ) func main() { req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20", nil) if err != nil { panic(err) } req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode) fmt.Println(string(body)) } ``` ```ruby Ruby theme={null} require "net/http" require "uri" uri = URI("https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD&page=1&size=20") request = Net::HTTP::Get.new(uri) request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "") response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.code puts response.body ``` ```json 200 theme={null} { "data": [ { "id": "2wHn5Qe8rT1yU4iO7pA3sD6fG9k", "url": "https://meusite.com.br/webhooks/finvia", "merchantId": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD", "enabledEvents": ["charge.paid", "charge.refunded", "charge.blocked", "payout.approved", "payout.rejected"], "includeSubmerchants": true, "gatewayId": "2bGt4Yh7Uj1Ik5Ol8Pz3Xc6Vb9N", "createdAt": "2026-10-20T13:45:00.000Z", "updatedAt": "2026-10-20T13:45:00.000Z", "deletedAt": null } ], "total": 1, "page": 1, "size": 20, "pages": 1 } ``` ```json 403 theme={null} { "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" } ``` ## Veja também > [card] [Criar endpoint](/referencia/webhooks/criar-endpoint) > > Cadastre um endpoint com filtro de eventos. > [card] [Atualizar endpoint](/referencia/webhooks/atualizar-endpoint) > > Troque a URL ou os eventos. > [card] [Excluir endpoint](/referencia/webhooks/excluir-endpoint) > > Pare de enviar eventos para uma URL. > [card] [Webhooks: visão geral](/guias/webhooks/visao-geral) > > Quem recebe cada evento e em que formato.