Integração de Pagamentos em Aplicativos Nativos — Wake Commerce

Público-alvo: parceiros técnicos que estão construindo aplicativos nativos (iOS/Android) ou aplicações headless que consomem as APIs da Wake e precisam fechar pedidos com pagamento — especialmente cartão de crédito.

Escopo desta versão: conector Wake Gateway . Os demais conectores seguirão o mesmo contrato em entregas futuras.

1. Visão geral

No Storefront web, o fechamento de pedidos com cartão é resolvido pelos scripts JS dos conectores, que a própria Wake injeta na página de checkout. Esses scripts:

1. Leem as configurações públicas do conector (public key, tipo de pagamento, etc.);
2. Tokenizam os dados do cartão diretamente no gateway de pagamento;
3. Enviam o token resultante na mutation checkoutComplete.

Em um app nativo não existe WebView com esses scripts — a sua aplicação precisa replicar esse fluxo por conta própria, via chamadas HTTP. Esta documentação descreve exatamente como fazer isso:

┌─────────────────────────────────────────────────────────────────┐
│ 1. Consultar o pagamento selecionado (Storefront API - GraphQL) │
│    → obter publicConfig: connectorName, paymentType, publicKey  │
├─────────────────────────────────────────────────────────────────┤
│ 2. Tokenizar o cartão direto no gateway (API pública da Vindi)  │
│    → obter gateway_token                                        │
├─────────────────────────────────────────────────────────────────┤
│ 3. Fechar o pedido (mutation checkoutComplete)                  │
│    → enviar paymentData com gateway-token + vindi-publickey     │
└─────────────────────────────────────────────────────────────────┘

2. Obtendo as configurações públicas do conector (publicConfig)

2.1 O campo publicConfig

O tipo GraphQL SelectedPaymentMethod da Storefront API expõe o campo opcional publicConfig: um dicionário chave-valor com as configurações públicas do conector de pagamento selecionado. Ele está disponível em todos os pontos do schema que retornam SelectedPaymentMethod:

• checkout.selectedPaymentMethod
• checkout.selectedPaymentMethods (multipagamento — cada item traz o seu próprio publicConfig)
• Nos CheckoutNode retornados pelas mutations de checkout

Exemplo de query:

query ($checkoutId: Uuid!) {
  checkout(checkoutId: $checkoutId) {
    selectedPaymentMethod {
      id
      installments { number value }
      publicConfig
    }
  }
}

Exemplo de retorno para Wake Gateway — Cartão:

{
  "publicConfig": {
    "connectorName": "WakeGateway",
    "paymentType": "Cartao",
    "publicKey": "tRxoUJDjxmvhPtlq4Ji8Hr3m41TNsSjSmKqzogxtnH8"
  }
}

Chaves disponíveis hoje (Wake Gateway):

Observações importantes:

• Os valores podem ser de qualquer tipo JSON — string, número, booleano ou até objetos/arrays aninhados. Trate o campo como um objeto JSON dinâmico.
• O campo é aditivo e opcional: quando o conector não expõe configuração pública (ou ainda não foi migrado para este contrato), publicConfig vem null. Trate esse caso no seu app.
• O contrato é extensível: novas chaves podem ser adicionadas a qualquer momento. Não faça parse posicional nem valide o conjunto exato de chaves — leia apenas as que você precisa.
• Os campos html e scripts continuam sendo retornados como antes (os mesmos dados aparecem duplicados nos input hidden do html). Não faça parse do HTML — esse formato existe apenas para o Storefront web e não é um contrato para integrações externas. Use sempre publicConfig.

2.2 Antes do publicConfig (fallback legado)

Em ambientes/conectores onde publicConfig ainda não estiver disponível, as mesmas informações existem como campos hidden no atributo html do pagamento selecionado (ex.: vindi-publickey, paymentType). Esse parse não é recomendado nem suportado como contrato — migre para publicConfig assim que disponível para o conector em uso.

3. Tokenizando o cartão (Wake Gateway)

Com a publicKey em mãos, o app deve tokenizar o cartão diretamente na API pública do gateway de ´pagamento, sem passar pelos servidores da Wake (os dados sensíveis do cartão nunca devem ser enviados às APIs da Wake).

Referência oficial: Vindi — Como cadastrar perfis de pagamento via API

Requisição (produção):

POST https://app.vindi.com.br/api/v1/public/payment_profiles
Authorization: Basic base64("{publicKey}:")
Content-Type: application/json

{
  "holder_name": "NOME IMPRESSO NO CARTAO",
  "card_expiration": "12/2030",
  "card_number": "4111111111111111",
  "card_cvv": "123",
  "payment_method_code": "credit_card",
  "payment_company_code": "visa"
}

Resposta (resumida):

{
  "payment_profile": {
    "gateway_token": "049d1d32-11f7-466c-9099-16e09dbc1234",
    "...": "..."
  }
}

Guarde o gateway_token — ele será enviado no checkoutComplete.

⚠️ Erros comuns na tokenização

4. Fechando o pedido (checkoutComplete)

Referência: Mutation CheckoutComplete

A mutation checkoutComplete fecha o carrinho e cria o pedido. Para cartão via Wake Gateway, o parâmetro paymentData é uma string no formato query string (chave=valor&chave=valor, com valores URL-encoded):

mutation ($checkoutId: Uuid!, $paymentData: String!) {
  checkoutComplete(checkoutId: $checkoutId, paymentData: $paymentData) {
    checkoutId
    completed
    orders { orderId }
  }
}

4.1 Campos do paymentData — Cartão (Wake Gateway)

paymentType=Cartao
&gateway-token={gateway_token obtido na tokenização}
&vindi-publickey={publicKey obtida no publicConfig}
&name=NOME%20DO%20TITULAR
&month=07
&year=2030
&expiry=07%2F2030
&cpf=12345678900
&number=
&cvc=
&saveCard=false

Campos principais (o pagamento em si):

Campos complementares (metadados não sensíveis):

Campos que devem ir vazios:

Campos clicktopay-*, finger_print, isSandbox, saveClickToPay, keepConnected: aparecem no tráfego do Storefront web e são específicos daquele contexto (Click to Pay / antifraude do checkout web). Não são necessários — e não devem ser enviados — em apps nativos.

4.2 Boleto e Pix

Para Boleto e Pix não há tokenização. O publicConfig retorna connectorName e paymentType, e o paymentData se resume a:

paymentType=Boleto

paymentType=Pix

4.3 Erros comuns no fechamento

5. Limitações conhecidas para apps nativos

• Click to Pay (CTP) não é suportado em aplicações mobile nativas. É uma limitação da Mastercard, não da Wake. A homologação para PWA está em andamento; para app nativo não há previsão. O fluxo de cartão comum via Wake Gateway (descrito acima) funciona normalmente sem CTP.
• Apple Pay / Google Pay têm requisitos próprios por plataforma e conector — trate como escopo à parte e valide com o time Wake antes de implementar.
• Esta primeira entrega do publicConfig cobre o Wake Gateway (Vindi). Para outros conectores (Pagar.me, Adyen, Cielo etc.), consulte a Wake sobre disponibilidade — o contrato do dicionário será o mesmo.

6. Checklist de implementação

• Consultar selectedPaymentMethod.publicConfig na Storefront API e tratar o caso null
• Usar connectorName para rotear o fluxo de tokenização correto
• Tokenizar o cartão direto na API pública da Vindi com a publicKey
• Detectar e enviar a bandeira (payment_company_code) corretamente
• Montar paymentData com gateway-token, vindi-publickey e paymentType, com number e cvc vazios
• Não enviar campos clicktopay-* no app
• Não fazer parse do html retornado pela API
• Testar fechamento com cartão, boleto e Pix em homologação antes de ir a produção

7. Referências

• Tokenize — Wake Commerce
• Integração de Pagamentos para Storefront 1.0 e 2.0
• Mutation CheckoutComplete
• Vindi — Cadastro de perfis de pagamento via API