> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# E-commerce de produtos físicos

> 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](https://docs.fastpaybrasil.com/integrar-com-ia.md).

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](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) |
| Parcelamento | Cartão de crédito com `installments` (de `1` a `12`) | `POST /v1/charges` · [Cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) |
| Autenticação do portador | 3DS gerenciado (`threeDSMode: "managed"`) | `POST /v1/charges` · [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md) |
| Carteira digital | Apple Pay (objeto `wallet`) | `POST /v1/charges` · [Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) |
| Entrega | `shippingAddress` e `trackingInfo` | `POST /v1/charges` |
| Atualização do pedido | Webhooks cadastrados no painel e `postbackUrl` | [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md) |
| Conferência de status | Consulta da cobrança | `GET /v1/charges/{id}` |
| Devolução | Estorno total | `POST /v1/refunds` · [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md) |
| Contestação | Bloqueio, pré-chargeback, chargeback e MED | [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) |
| Recompra | Cliente, cofre de cartões e cobrança com `cardTokenId` | `POST /v1/customers`, `POST /v1/cards` · [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) |

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<br/>no site ou no iPhone"]):::comprador
    F["Checkout da Trilha Leve<br/>chave pública pk_"]:::lojista
    S["Servidor da loja<br/>chave secreta sk_"]:::lojista
    API["Finvia API"]:::finvia
    ADQ["Adquirente e bandeiras<br/>cartão e Apple Pay"]:::externo
    PIX["Sistema Pix<br/>banco do comprador"]:::externo
    EV[["Eventos charge.*<br/>paid · refunded · blocked"]]:::evento
    AUT["Página 3DS da Finvia<br/>authenticationUrl"]:::finvia
    W["Receptor de webhooks<br/>endpoint e postbackUrl"]:::lojista
    P["Sistema de pedidos<br/>e estoque"]:::lojista
    OK(["Pedido pago<br/>vai para separação"]):::ok
    C -->|"1. escolhe Pix, cartão<br/>ou Apple Pay"| F
    F -->|"2. envia o pedido"| S
    S ==>|"3. POST /v1/charges<br/>pix ou credit_card<br/>Apple Pay com wallet"| API
    API -.->|"4. 201 com o status<br/>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<br/>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<br/>QR Code na tela<br/>estoque reservado 15 min"]:::alerta
    R{"Resposta<br/>da criação?"}:::decisao
    AUT["authentication_required<br/>comprador na<br/>authenticationUrl"]:::alerta
    AN["in_analysis<br/>revisão do antifraude"]:::alerta
    FIM{"Resultado<br/>final?"}:::decisao
    REC["refused ou failed<br/>oferece outra forma"]:::erro
    EXP["Pix expirado<br/>charge.updated failed<br/>libera a reserva"]:::erro
    PAID["paid<br/>pedido pago<br/>vai para separação"]:::ok
    REF["refunded<br/>devolvido, item<br/>volta ao estoque"]:::neutro
    BLK["isBlocked: true<br/>pedido em disputa"]:::alerta
    CB["chargeback<br/>registra a perda"]:::erro
    INI --> Q
    Q -->|"Pix"| PEN
    Q -->|"cartão ou<br/>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<br/>não autorizado"| REC
    PAID -->|"devolução<br/>POST /v1/refunds"| REF
    PAID -->|"contestação<br/>charge.blocked"| BLK
    BLK -.->|"bloqueio liberado<br/>consulte isBlocked"| PAID
    BLK -->|"alerta devolvido<br/>charge.refunded"| REF
    BLK -->|"formalizado<br/>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 `<img>`). 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](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md).

> [!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](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

**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](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md).
* **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](https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md).

> [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](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) ou com as [rotas de 3DS](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md) 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](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md).

## 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](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

## Veja também

> [card] [Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md)
>
> Validade, QR Code e confirmação do pagamento.

> [card] [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md)
>
> Autenticação conduzida pela Finvia.

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Eventos, envelopes e o canal de postback.

> [card] [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)
>
> Como acompanhar e responder a uma disputa.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.