Como construir um payment app na Shopify em 2026

Em 2026 o ecossistema de pagamentos da Shopify amadureceu de forma significativa. Com mais de 4,7 milhões de lojistas ativos e um GMV acima de US$ 250 bilhões por ano, a demanda por payment apps customizados — especialmente em mercados como o Brasil — nunca foi tão alta.

Seja para integrar um gateway local com Pix, Boleto Bancário ou BNPL, seja para entregar experiências de checkout customizadas a lojistas Shopify Plus, construir um Payment App exige entendimento profundo da arquitetura da plataforma. Este guia cobre o caminho completo, do setup inicial à aprovação na Shopify App Store.

01Arquitetura de um payment app na Shopify

Um Payment App não é um app de storefront: ele se integra diretamente ao checkout e ao ciclo de vida do pedido pela Payments Apps API. Diferente de gateways tradicionais configurados no admin, ele atua como provedor de pagamento completo, com controle total sobre a experiência.

"Payment Apps são a evolução dos gateways customizados — permitem construir experiências de pagamento nativas dentro do checkout da Shopify, sem atrito e com controle total do fluxo de dados."— Shopify Developer Documentation, 2025

Fluxo de dados simplificado

Quando o cliente clica em "Finalizar compra", a Shopify cria uma Payment Session e chama o endpoint /payment do seu app. O backend conversa com o gateway externo, atualiza a sessão via mutation GraphQL, e a Shopify finaliza ou cancela o pedido conforme o status retornado.

02Pré-requisitos e setup do ambiente

Antes de escrever uma única linha de código, garanta que o ambiente está corretamente configurado:

03Criando o app no Partner Dashboard

Com o ambiente configurado, gere o scaffold pelo Shopify CLI — o template de Payment App já vem com as extensões necessárias:

# Cria o projeto com o template oficial
shopify app init my-payment-app

# Selecione: Payment App
# Framework: Node.js (recomendado) ou Ruby

cd my-payment-app
npm install

# Sobe o servidor de desenvolvimento
shopify app dev

O CLI cria o app no Partner Dashboard, configura as callback URLs e abre um túnel HTTPS para o servidor local.

Configurando permissões (scopes)

No arquivo shopify.app.toml, configure os scopes necessários para um Payment App:

[scopes]
scopes = "write_payment_sessions,write_payment_gateways,write_orders,read_checkouts"

[[extensions]]
type   = "payments_extension"
name   = "My Payment Provider"
handle = "my-payment-provider"

  [extensions.capabilities]
  network_access = true

  [extensions.settings]
  api_version               = "2025-04"
  start_payment_session_url = "/api/payment"
  start_refund_session_url  = "/api/refund"
  start_capture_session_url = "/api/capture"
  start_void_session_url    = "/api/void"

04Trabalhando com a Payments Apps API

A Payments Apps API é uma extensão da Admin API GraphQL, disponível exclusivamente para payment apps aprovados. Ela expõe mutations para atualizar o status das sessões de pagamento, captura, estorno e cancelamento.

Principais mutations

Exemplo: resolvendo uma payment session

mutation PaymentSessionResolve($id: ID!) {
  paymentSessionResolve(id: $id) {
    paymentSession {
      id
      state {
        ... on PaymentSessionStateResolved {
          code
        }
      }
      nextAction {
        action
        context {
          ... on PaymentSessionActionsRedirect {
            redirectUrl
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

05Implementando o fluxo completo de pagamento

O coração do app é o endpoint que recebe a requisição da Shopify quando o cliente tenta pagar. Uma implementação em Node.js com Express:

import express from 'express';
import { resolvePaymentSession, rejectPaymentSession } from '../utils/shopify-mutations.js';
import { chargeWithGateway } from '../utils/gateway.js';

const router = express.Router();

// A Shopify chama este endpoint quando o checkout inicia
router.post('/api/payment', async (req, res) => {
  const {
    id,             // ID da payment session
    gid,            // GID global da Shopify
    amount,         // Valor em centavos
    currency,       // Ex.: "BRL"
    test,           // true em ambiente de teste
    customer,       // Dados do cliente
    payment_method  // Dados do método de pagamento
  } = req.body;

  // Responde 200 imediatamente para evitar timeout da Shopify
  res.status(200).json({ received: true });

  try {
    const chargeResult = await chargeWithGateway({
      amount, currency, customer, payment_method, test
    });

    if (chargeResult.status === 'approved') {
      await resolvePaymentSession(gid);
    } else {
      await rejectPaymentSession(gid, {
        reason: 'PAYMENT_METHOD_DECLINED',
        merchantMessage: chargeResult.message
      });
    }
  } catch (error) {
    console.error('Payment processing error:', error);
    await rejectPaymentSession(gid, {
      reason: 'INTERNAL_ERROR',
      merchantMessage: 'Erro interno. Tente novamente.'
    });
  }
});

export default router;

Suporte a pagamentos pendentes (Pix e Boleto)

Para métodos assíncronos, use paymentSessionPending com um webhook de callback. A Shopify mantém o pedido pendente até você chamar resolve (ou reject) na confirmação do gateway.

// Gera o código Pix ou o boleto no gateway
const pixResult = await gateway.createPixPayment({ amount, currency });

// Informa à Shopify que o pagamento está pendente
await client.request(
  `mutation PaymentSessionPending($id: ID!, $pendingExpiresAt: DateTime!) {
    paymentSessionPending(
      id: $id,
      pendingExpiresAt: $pendingExpiresAt,
      reason: WAIT_FOR_CUSTOMER
    ) {
      paymentSession { id state { ... } }
      userErrors { field message }
    }
  }`,
  {
    variables: {
      id: gid,
      // Boleto expira em 3 dias; Pix, em 30 minutos
      pendingExpiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString()
    }
  }
);

06Webhooks obrigatórios e tratamento de eventos

Todo payment app aprovado precisa implementar um conjunto mínimo de webhooks para GDPR e ciclo de vida da loja.

import crypto from 'crypto';

function validateWebhook(rawBody, hmacHeader, secret) {
  const digest = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('base64');

  return crypto.timingSafeEqual(
    Buffer.from(digest),
    Buffer.from(hmacHeader)
  );
}

07PCI DSS, 3DS2 e compliance

Construir um app de pagamento significa lidar com dados financeiros sensíveis. O nível de compliance exigido depende de quais dados o app toca diretamente.

Níveis de PCI DSS

A maioria dos payment apps opera no modelo SAQ A (o menos restritivo), porque a captura dos dados de cartão acontece no gateway parceiro, via iFrame ou redirect — seu backend nunca vê o cartão. Se você processa dados de cartão diretamente, precisa de certificação SAQ D ou auditoria completa por QSA.

3D Secure 2 (3DS2) em 2026

Na Europa — e cada vez mais no Brasil, por exigência do Banco Central — o 3DS2 é obrigatório para autenticação forte do cliente (SCA). A Shopify suporta 3DS2 nativamente pelo campo threeDS da payment session: você precisa repassar o resultado da autenticação junto com o resultado da cobrança.

08Testando com o sandbox da Shopify

A Shopify oferece um ambiente de testes robusto para payment apps. Use sua development store com o test mode habilitado para simular todos os cenários de pagamento sem transações reais.

Cenários de teste obrigatórios

09Publicando na App Store

A submissão de um payment app é mais rigorosa que a de apps convencionais: a Shopify faz um review manual de segurança que leva de 2 a 6 semanas.

Conclusão — o mercado de payment apps no Brasil em 2026

O Brasil é hoje um dos mercados mais dinâmicos para payment apps no ecossistema Shopify. A combinação de Pix como método dominante, crescimento do BNPL e a migração de operações brasileiras para o Shopify Plus criou uma janela única para desenvolvedores especializados.

Construir um payment app robusto exige domínio técnico em várias frentes — GraphQL, webhooks, compliance financeiro — mas o retorno para quem domina essa stack é significativo. Lojistas pagam por soluções confiáveis que se integrem nativamente ao checkout com os métodos que seus clientes já conhecem.

Na AM Lab já construímos payment apps para fintechs como Barte e Divibank, e a lição é clara: a chave está em uma arquitetura assíncrona sólida, tratamento cuidadoso de erros e um processo de QA que cubra todos os cenários de falha antes da submissão.