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, PagarMe, Mercado Pago e Adyen . Os demais conectores seguirão o mesmo contrato em entregas futuras.

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.
4. 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:

Conectores Suportados

O campo publicConfig está disponível nos seguintes conectores:

• Wake Gateway
• Pagar.me
• Adyen
• Mercado Pago

Fluxo de Integração

O processo segue três etapas sequenciais, independentemente do conector utilizado:

ETAPA 1 DE 3
Obter configurações públicas via publicConfig

O campo publicConfig, presente em SelectedPaymentMethod na resposta da Storefront API, expõe as credenciais e metadados públicos do conector ativo. Use essas informações para identificar o gateway e inicializar o fluxo de tokenização correto.

Formato do dicionário

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.

Exemplos por conector

Wake Gateway

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

Pagar.me

{
  "connectorName": "PagarMeV5",
  "paymentType":   "Cartao",
  "publicKey":     "pk_live_xxxxxxxxxxxxxxxx"
}

Adyen

{
  "connectorName":   "Adyen",
  "paymentType":     "Cartao",
  "publicKey":       "test_XXXXXXXXXXXXXXXXXXXXXXXX", // 
}

Mercado Pago

{
  "connectorName": "MercadoPago",
  "paymentType":   "Cartao",
  "publicKey":     "APP_USR-xxxx-xxxx-xxxx-xxxxxxxxxxxx" // 
}

ETAPA 2 DE 3
Tokenização do cartão

Cada conector utiliza sua própria API para tokenização. Envie os dados sensíveis do cartão diretamente ao gateway — nunca trafegue número, CVV ou dados de expiração pelo seu servidor. O token resultante é usado na Etapa 3.

Wake Gateway

Referência oficial: https://atendimento.vindi.com.br/a/115009609107-Como-eu-cadastro-perfis-de-pagamento-via-API

Endpoint: POST https://app.vindi.com.br/api/v1/public/payment_profiles

Autenticação
Basic Auth com base64("{publicKey}:") — note os dois-pontos sem senha.

Payload

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

Resposta — campo relevante

JSON · RESPONSE
{
  "payment_profile": {
    "gateway_token": "1ab2c3d4e5f6..."
  }
}

Pagar.me — API v5

Referência oficial: https://docs.pagar.me/reference/pagarme-js

Validade do token: O token expira em até 60 segundos e é de uso único. Após o uso, o cartão é adicionado à wallet do cliente. Gere um novo token a cada tentativa de pagamento.

Adyen — Client-Side Encryption (CSE)

Referência oficial: https://docs.adyen.com/development-resources/testing/tokenization

Passo 1 — Inicializar a SDK com a publicKey

import Adyen


let context = AdyenContext(
    apiContext: try APIContext(
        environment: .live,
        clientKey: publicConfig.publicKey
    ),
    payment: Payment(amount: amount, countryCode: "BR")
)
let component = CardComponent(paymentMethod: cardPaymentMethod, context: context)

val context = AdyenContext(
    apiContext = ApiContext(
        environment = Environment.EUROPE,
        clientKey = publicConfig.publicKey
    ),
    payment = Payment(amount = amount, countryCode = "BR")
)
val component = CardComponent(paymentMethod, context)

Passo 2 — Campos retornados pela SDK (já encriptados)

{
  "encryptedCardNumber":   "adyenjs_0_1_25$...",
  "encryptedExpiryMonth":  "adyenjs_0_1_25$...",
  "encryptedExpiryYear":   "adyenjs_0_1_25$...",
  "encryptedSecurityCode": "adyenjs_0_1_25$...",
  "holderName":            "NOME NO CARTAO"
}

Mercado Pago — Card Token API

Referência oficial: https://www.mercadopago.com.br/developers/pt/docs/subscriptions/additional-content/cardtoken

Validade do token: O CardToken é de uso único e expira em 7 dias. Use-o imediatamente após a geração.

ETAPA 3 DE 3
Fechar 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 }
  }
}

Com o token em mãos, finalize o pedido via checkoutComplete na Storefront API. O campo paymentData é uma string no formato application/x-www-form-urlencoded. Dados sensíveis do cartão nunca devem ser enviados — apenas o token gerado na Etapa 2.

Exemplos por conector:

Wake Gateway

paymentType=Cartao
&gateway-token={gateway_token_da_vindi}
&vindi-publickey={publicKey}
&name={titular_url_encoded}
&month=07
&year=2030
&expiry=07%2F2030
&cpf=12345678900
&number=
&cvc=

Pagar.me

paymentType=Cartao
&chaveCartao={id_token_pagarme}
&name={titular_url_encoded}
&month=07
&year=2030
&expiry=07%2F2030
&cpf=12345678900
&number=
&cvc=

Adyen

paymentType=Cartao
&name={holderName}
&month={encryptedExpiryMonth}
&year={encryptedExpiryYear}
&cpf=12345678900
&number={encryptedCardNumber}
&cvc={encryptedSecurityCode}

Mercado Pago

paymentType=Cartao
&token={id_token_mercadopago}
&name={titular_url_encoded}
&payment_method_id={bandeira}
&month=07
&year=2030
&expiry=07%2F2030
&cpf=12345678900
&number=
&cvc=

Outras Formas de Pagamento

Boleto e Pix não exigem tokenização. Envie diretamente no paymentData apenas o tipo de pagamento:

paymentType=Boleto

paymentType=Pix

Limitações Conhecidas

Checklist de implementação

• Verificar publicConfig não-nulo antes de tentar tokenização
• Usar connectorName para rotear o fluxo de tokenização correto
• Detectar e enviar a bandeira (payment_company_code) corretamente
• Não fazer parse do campo html — usar apenas publicConfig
• Enviar number e cvc vazios no paymentData (dados já representados pelo token)
• Não enviar campos clicktopay-* no app
• Inicializar SDK Adyen com a publicKey do publicConfig (pendente confirmação de campos)
• Testar com cartão, boleto e Pix em homologação para cada conector