Ambiente de Pagamento

🔒 Visão Geral

O pagamento no checkout Uappi é processado por um iframe isolado, servido pelo domínio:

1https://payments.uappi.store
https://payments.uappi.store

Esse isolamento garante que os dados sensíveis do pagamento (dados de cartão, tokens, etc.) nunca trafeguem pelo código do checkout — eles ficam restritos ao ambiente controlado da Uappi.

O iframe é autocontido: renderiza o formulário adequado ao tipo de pagamento, processa o submit internamente e comunica o resultado de volta ao checkout via postMessage.

🔑 Pré-requisito: Token de Pagamento

Antes de montar o iframe, o checkout precisa obter um token de pagamento assinado. Esse token autentica a sessão e carrega o contexto do carrinho (loja, política comercial, cliente, moeda e opção de pagamento selecionada).

O token é gerado via:

> POST /cart/payment-token — ver documentação completa

O token tem validade de 15 minutos. Após esse prazo, o iframe rejeitará a requisição e um novo token deverá ser gerado antes de recarregar o src do iframe.

🧩 Montando o iframe

A URL do iframe é composta pela base do ambiente de pagamento seguida dos parâmetros de query:

1https://payments.uappi.store?token={TOKEN}&lang={LOCALE}&ctaColor={COR}&countryCode={PAIS}
https://payments.uappi.store?token={TOKEN}&lang={LOCALE}&ctaColor={COR}&countryCode={PAIS}

Parâmetros de Query

Parâmetro	Obrigatório	Tipo	Descrição
`token`	✅	string	Token de pagamento gerado pelo endpoint `/cart/payment-token`
`lang`	❌	string	Código de localização para internacionalização do formulário (ex: `pt-BR`, `en-US`)
`ctaColor`	❌	string	Cor hexadecimal do botão de confirmação sem o `#` (ex: `fe4f02`). Máx. 8 caracteres.
`countryCode`	❌	string	Código Alpha-3 do país para pré-selecionar o DDI no campo de telefone (ex: `BRA`, `USA`). Padrão: `BRA`

Exemplo de URL

1https://payments.uappi.store?token=eyJjYXJ0SWQi...&lang=pt-BR&ctaColor=003777&countryCode=BRA
https://payments.uappi.store?token=eyJjYXJ0SWQi...&lang=pt-BR&ctaColor=003777&countryCode=BRA

Exemplo de implementação HTML

1<iframe
2  id="payment-iframe"
3  src="https://payments.uappi.store?token=SEU_TOKEN_AQUI&lang=pt-BR&ctaColor=003777"
4  style="width: 100%; border: none; min-height: 400px;"
5  allow="payment"
6></iframe>
<iframe
  id="payment-iframe"
  src="https://payments.uappi.store?token=SEU_TOKEN_AQUI&lang=pt-BR&ctaColor=003777"
  style="width: 100%; border: none; min-height: 400px;"
  allow="payment"
></iframe>

ℹ️ Informação

O domínio do checkout deve estar autorizado na plataforma Uappi. O iframe valida o header Referer da requisição e bloqueia a renderização para domínios não autorizados.

💳 Tipos de Pagamento Suportados

O iframe detecta automaticamente o tipo de pagamento a partir do token e renderiza o formulário adequado.

Tipo (`paymentType`)	Formulário renderizado
`credit-card`	Formulário completo de cartão de crédito (número, CVV, validade, titular, parcelas)
`debit-card`	Formulário completo de cartão de débito
`pix`	Botão de confirmação (QR Code retornado via evento de sucesso)
`billet`	Botão de confirmação (dados do boleto retornados via evento de sucesso)
`external`	Botão de confirmação com redirecionamento externo
`internal-deposit`	Botão de confirmação de depósito interno
`custom`	Botão de confirmação personalizado
`incorporated`	Iframe externo da integração de pagamento incorporado

📬 Eventos `postMessage`

O iframe comunica seu estado e o resultado do pagamento ao checkout por meio de eventos postMessage. O checkout deve registrar um listener em window para recebê-los.

Como ouvir os eventos

1window.addEventListener('message', function (event) {
2  const { type, paymentType, data } = event.data;
3
4  switch (type) {
5    case 'UAPPI_PAYMENT_READY':
6      // ✅ iframe carregou e está pronto para interação
7      break;
8
9    case 'UAPPI_PAYMENT_SUCCESS':
10      // 🎉 Pagamento concluído — redirecionar para página de confirmação
11      break;
12
13    case 'UAPPI_PAYMENT_REDIRECT':
14      // 🔀 Pagamento externo — redirecionar o cliente para event.data.url
15      window.location.href = event.data.url;
16      break;
17
18    case 'UAPPI_PAYMENT_ERROR':
19      // ⚠️ Falha no pagamento — exibir mensagem ou permitir nova tentativa
20      break;
21  }
22});
window.addEventListener('message', function (event) {
  const { type, paymentType, data } = event.data;
  switch (type) {
    case 'UAPPI_PAYMENT_READY':
      // ✅ iframe carregou e está pronto para interação
      break;
    case 'UAPPI_PAYMENT_SUCCESS':
      // 🎉 Pagamento concluído — redirecionar para página de confirmação
      break;
    case 'UAPPI_PAYMENT_REDIRECT':
      // 🔀 Pagamento externo — redirecionar o cliente para event.data.url
      window.location.href = event.data.url;
      break;
    case 'UAPPI_PAYMENT_ERROR':
      // ⚠️ Falha no pagamento — exibir mensagem ou permitir nova tentativa
      break;
  }
});

✅ `UAPPI_PAYMENT_READY`

Emitido assim que o iframe termina de carregar e está pronto para receber interação do usuário. Ideal para esconder spinners de carregamento ou habilitar elementos da UI.

1{
2  "type": "UAPPI_PAYMENT_READY",
3  "paymentType": "credit-card"
4}
{
  "type": "UAPPI_PAYMENT_READY",
  "paymentType": "credit-card"
}

Campo	Tipo	Descrição
`type`	string	Sempre `UAPPI_PAYMENT_READY`
`paymentType`	string	Tipo de pagamento que foi renderizado no iframe

🎉 `UAPPI_PAYMENT_SUCCESS`

Emitido quando o pagamento é processado com sucesso e o pedido é criado. O campo data contém o objeto do grupo de pedido retornado pelo backend.

1{
2  "type": "UAPPI_PAYMENT_SUCCESS",
3  "paymentType": "credit-card",
4  "data": {
5    "id": 345,
6    "cartId": "ac66ca1d61577b216979169",
7    "tradePolicyId": 1,
8    "userId": null,
9    "userEmail": null,
10    "userName": null,
11    "code": "345",
12    "salesChannelDomain": "sua-loja.com.br",
13    "marketplaceId": null,
14    "marketplaceName": null,
15    "marketplaceStoreCredentialId": null,
16    "marketplaceOrderGroupId": null,
17    "currency": "BRL",
18    "createdAt": "2026-04-27 10:00:00",
19    "issuedAt": "2026-04-27 10:05:00"
20  }
21}
{
  "type": "UAPPI_PAYMENT_SUCCESS",
  "paymentType": "credit-card",
  "data": {
    "id": 345,
    "cartId": "ac66ca1d61577b216979169",
    "tradePolicyId": 1,
    "userId": null,
    "userEmail": null,
    "userName": null,
    "code": "345",
    "salesChannelDomain": "sua-loja.com.br",
    "marketplaceId": null,
    "marketplaceName": null,
    "marketplaceStoreCredentialId": null,
    "marketplaceOrderGroupId": null,
    "currency": "BRL",
    "createdAt": "2026-04-27 10:00:00",
    "issuedAt": "2026-04-27 10:05:00"
  }
}

Campo	Tipo	Descrição
`type`	string	Sempre `UAPPI_PAYMENT_SUCCESS`
`paymentType`	string	Tipo de pagamento utilizado
`data`	object	Objeto do grupo de pedido criado
`data.id`	integer	ID do grupo de pedido
`data.cartId`	string	ID do carrinho de origem
`data.code`	string	Código de referência do pedido
`data.currency`	string	Moeda utilizada na transação
`data.createdAt`	string	Data/hora de criação do pedido
`data.issuedAt`	string	Data/hora de emissão do pedido

🔀 `UAPPI_PAYMENT_REDIRECT`

Emitido quando o tipo de pagamento exige redirecionamento para um ambiente externo (ex: pagamento via external). O checkout deve redirecionar o cliente para data.url — o iframe não realiza o redirecionamento automaticamente.

1{
2  "type": "UAPPI_PAYMENT_REDIRECT",
3  "paymentType": "external",
4  "url": "https://gateway-externo.com.br/pay?cartId=ac66ca1d61577b216979169",
5  "data": {
6    "cartId": "ac66ca1d61577b216979169",
7    "paymentOptionId": 14,
8    "paymentUrl": "https://gateway-externo.com.br/pay?cartId=ac66ca1d61577b216979169"
9  }
10}
{
  "type": "UAPPI_PAYMENT_REDIRECT",
  "paymentType": "external",
  "url": "https://gateway-externo.com.br/pay?cartId=ac66ca1d61577b216979169",
  "data": {
    "cartId": "ac66ca1d61577b216979169",
    "paymentOptionId": 14,
    "paymentUrl": "https://gateway-externo.com.br/pay?cartId=ac66ca1d61577b216979169"
  }
}

Campo	Tipo	Descrição
`type`	string	Sempre `UAPPI_PAYMENT_REDIRECT`
`paymentType`	string	Tipo de pagamento utilizado
`url`	string	URL de destino para redirecionamento (atalho para `data.paymentUrl`)
`data.cartId`	string	ID do carrinho de origem
`data.paymentOptionId`	integer	ID da opção de pagamento selecionada
`data.paymentUrl`	string	URL completa do ambiente de pagamento externo

⚠️ `UAPPI_PAYMENT_ERROR`

Emitido quando o pagamento falha, seja por recusa do gateway, validação inválida ou problema de rede. O iframe já exibe a mensagem de erro internamente — o checkout pode usá-la para logs ou para montar uma UI própria de fallback.

1{
2  "type": "UAPPI_PAYMENT_ERROR",
3  "paymentType": "credit-card",
4  "errorCode": "UAPPI_STORE_ORDER_PAYMENT_FAIL",
5  "message": "Pagamento recusado. Verifique os dados do cartão e tente novamente."
6}
{
  "type": "UAPPI_PAYMENT_ERROR",
  "paymentType": "credit-card",
  "errorCode": "UAPPI_STORE_ORDER_PAYMENT_FAIL",
  "message": "Pagamento recusado. Verifique os dados do cartão e tente novamente."
}

Campo	Tipo	Descrição
`type`	string	Sempre `UAPPI_PAYMENT_ERROR`
`paymentType`	string	Tipo de pagamento utilizado
`errorCode`	string \	null	Código interno do erro. Pode ser `null` em caso de falha de rede.
`message`	string	Mensagem de erro legível pelo usuário

🛡️ Segurança

O iframe de pagamento aplica automaticamente as seguintes medidas de segurança:

🔍 Validação de domínio: o header Referer é verificado contra os domínios autorizados na plataforma. Domínios não autorizados recebem um erro imediatamente.
🚫 CSP com frame-ancestors: o iframe só pode ser embutido nos domínios autorizados, bloqueando clickjacking no nível do browser.
⏱️ Token com expiração: o token é assinado via HMAC-SHA256 e expira em 15 minutos. Tokens expirados ou adulterados são rejeitados.
🗑️ Sem cache: os formulários de pagamento nunca são armazenados em cache pelo browser (Cache-Control: no-store).
🔐 HTTPS forçado: em produção, o header HSTS garante que todas as conexões futuras ao ambiente de pagamento usem HTTPS.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO