Documentação, do token ao repasse.

{
  "store_id": "MINHA_STORE",
  "external_id": "PED_1042",
  "idempotency_key": "PED_1042_v1",
  "seller_id": "seller_123",
  "customer": { "email": "[email protected]", "name": "Ana Lima" },
  "order": {
    "amount": 15000,
    "items": [
      { "desc": "Plano anual", "qty": 1, "price": 15000 }
    ]
  },
  "iat": 1760000000,
  "exp": 1760001800
}

• store_id · iss stringobrigatório

  Identifica a store. O servidor usa store_id e, se ausente, iss. A assinatura é conferida com o ORDER_SECRET dessa store.

• idempotency_key stringobrigatório

  Única por pedido dentro da store. A mesma chave devolve o pedido já criado, sem duplicar os itens. Se for omitida, todos os pedidos sem chave colidem e o servidor devolve sempre o primeiro.

• order.amount inteiroobrigatório

  Total do pedido, em centavos. Precisa ser maior que zero para o pagamento ser aceito.

• order.items[] arrayrecomendado

  Itens do pedido: desc, qty e price (em centavos). Aparecem no resumo do checkout.

• external_id stringrecomendado

  ID do pedido no seu sistema. Fica guardado no pedido.

• seller_id stringopcional

  O external_id do recebedor cadastrado no onboarding; habilita o split. Numa store com modo marketplace ligado é obrigatório (400 sem ele); nas demais é ignorado.

• split_rule stringopcional

  Nome de uma regra de split cadastrada em Admin → Regras de split. Vale antes da regra do vendedor e do padrão da store, nas formas de pagamento que ela define. Só em store marketplace; se o nome não existir na store, a troca do token falha com 400.

• customer objetoopcional

  JSON livre, guardado no pedido. O painel exibe name e email.

• iat · exp númerorecomendado

  Emissão e expiração (segundos Unix). Se exp existir, é verificada. Recomendado: 30 minutos.

Quando o token é recusado

• 400session_key is required

  O parâmetro session_key não foi enviado.

• 400Invalid token format

  O valor não é um JWT.

• 400Store ID (iss) is required

  O token não traz store_id nem iss.

• 401Store keys not found

  Não existe store com esse identificador.

• 401Invalid token signature or expired

  Assinatura inválida (outro segredo) ou token expirado.

• 400seller_id is required for marketplace stores

  A store está em modo marketplace e o token não traz seller_id.

• 404Seller not found

  O seller_id não corresponde a nenhum recebedor dessa store.

• 500Internal error processing order

  Falha ao gravar o pedido; tente de novo.

Para quem paga, o checkout hospedado tem duas etapas e nenhuma forma de pagamento vem escolhida. Na I · Forma de pagamento aparecem só as formas que a store ligou em Integrações. Escolhendo cartão, os campos do cartão surgem abaixo e o Prosseguir, sempre visível, só é liberado quando todos estiverem válidos; Pix e boleto liberam na hora. Na II · Seus dados ele informa contato, nome e CPF/CNPJ e endereço de cobrança, e paga. O endereço pergunta primeiro só o CEP: ao informá-lo, o restante abre já preenchido; se o CEP não for encontrado (ou a consulta falhar), o formulário completo abre vazio para ser digitado. O botão Alterar (ou o voltar do navegador) retorna à etapa I sem apagar nada; se a store tem uma única forma, ela já vem escolhida.

Status do pedido

O webhook POST /api/v1/webhooks/pagarme atualiza o status local de acordo com o evento recebido.

Todo pedido começa em pending. Quando o Temporal está ativo, a resposta do checkout traz status: "processing" até o workflow concluir.

1. i

   O admin gera o convite. No painel, em Convites, “Gerar convite” cria um JWT de 7 dias assinado com SELLER_JWT_SECRET.

2. ii

   Você envia o link. /onboarding?token=<convite>. Acrescente &storeId=<store>&externalId=<id-no-seu-sistema> para vincular o recebedor ao seu sistema.

3. iii

   O recebedor se cadastra em quatro passos: identificação, endereço, dados bancários e repasses.

4. iv

   O servidor registra. POST /api/v1/recipients (com o convite em Authorization: Bearer) cria o recebedor no Pagar.me (na conta da store) e o salva com o status devolvido pelo gateway e o external_id. O e-mail é único por store: um e-mail que já é vendedor da store devolve 409, porque o cadastro nunca sobrescreve um vendedor existente.

Do cadastro ao split

// domain/provider.go — o contrato mínimo de um gateway
type Provider interface {
	ProcessPayment(ctx context.Context, req PaymentRequest) (*PaymentResponse, error)
	RegisterSeller(ctx context.Context, params SellerParams) (*SellerResponse, error)
}

Um adaptador precisa, no mínimo, de duas coisas: ProcessPayment (cria a cobrança com as regras de split e devolve o ProviderOrderID e o status) e RegisterSeller (cadastra o recebedor e devolve o ProviderSellerID e o status). Na prática, ele também traduz os webhooks do gateway para os status locais.

O checkout hospedado pode vestir a sua marca. Em Admin → Alfaiataria você escolhe o nome e o logo, a cor da marca, o destaque, o corte dos cantos e a tipografia, e vê o resultado ao vivo, no papel claro e no escuro, antes de salvar.

Pela API

O painel usa estes dois endereços, protegidos pela sessão do admin. O PUT aceita os campos acima; o que for omitido volta ao padrão, e um valor inválido devolve 400 com a mensagem de cada campo.

# Lê o tema atual (cookie de sessão do admin)
curl -b cookies.txt https://checkout.suaempresa.com/api/v1/admin/theme

# Salva: campos omitidos voltam ao padrão
curl -b cookies.txt -X PUT https://checkout.suaempresa.com/api/v1/admin/theme \
  -H "Content-Type: application/json" \
  -d '{"name":"Ateliê Lume","brand":"#0f5c63","accent":"#b8892a","font":"elegante","corners":"redondos"}'

{
  "theme": {
    "name": "Ateliê Lume",
    "logo_url": "https://suaempresa.com/logo.png",
    "brand": "#0f5c63",
    "accent": "#b8892a",
    "font": "elegante",
    "corners": "redondos"
  },
  "defaults": { "brand": "#1b1713", "accent": "#b8341a", "font": "classica", "corners": "suaves", "name": "", "logo_url": "" },
  "store_id": "MINHA_STORE"
}

{ "errors": { "logo_url": "O logo precisa ser servido por https." } }

No checkout, o tema chega junto do pedido: GET /api/v1/orders/{id} devolve o campo theme. Se a store não personalizou nada, ou se a leitura falhar, o campo some e a página mantém o visual padrão. Um tema nunca impede um pagamento.

A mudança vale a partir do próximo checkout aberto: não há deploy nem reinício. Pedidos que já estão abertos na tela de quem paga mantêm o visual com que foram carregados.

Uma store é uma separação: tem os seus próprios pedidos, vendedores, convites, visual (Alfaiataria) e integrações. Só o identificador é obrigatório (o store_id que vai nos tokens); o nome é opcional. Uma mesma conta de admin gerencia várias stores: o seletor no topo do painel troca a store em que tudo trabalha, e Nova store cria outra.

# Cria uma store (o identificador sai do nome, se omitido) e passa a trabalhar nela
curl -b cookies.txt -X POST https://checkout.suaempresa.com/api/v1/admin/stores \
  -H "Content-Type: application/json" -d '{"label":"Ateliê Lume"}'
curl -b cookies.txt -X POST https://checkout.suaempresa.com/api/v1/admin/stores/switch \
  -H "Content-Type: application/json" -d '{"store_id":"ATELIE_LUME"}'

# Cadastra o Pagar.me da store e liga só cartão e boleto
curl -b cookies.txt -X PUT https://checkout.suaempresa.com/api/v1/admin/integrations/gateways/pagarme \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"fields":{"secret_key":"sk_…","public_key":"pk_…"}}'
curl -b cookies.txt -X PUT https://checkout.suaempresa.com/api/v1/admin/integrations/methods \
  -H "Content-Type: application/json" \
  -d '{"methods":{"card":{"enabled":true,"gateway":"pagarme"},"pix":{"enabled":false,"gateway":"pagarme"},"boleto":{"enabled":true,"gateway":"pagarme"}}}'

Modo marketplace

O modo marketplace é uma opção da integração com o Pagar.me v5, a única que faz split até o momento: o interruptor fica no cartão do Pagar.me, em Integrações. Ligado, a store vende por vendedores e só o Pagar.me pode ser usado (a API recusa rotear uma forma para outro gateway). Desligado, a store vende direto: não há vendedores nem split, um seller_id no token é ignorado e o painel esconde Vendedores e Convites.

• Só liga com o Pagar.me ativo e com chaves (da store ou da instalação), e sem nenhuma forma de pagamento em outro gateway.
• Enquanto estiver ligado, o Pagar.me não pode ser desativado na store, nem ter as chaves da store removidas se a instalação não tiver chaves para assumir: primeiro se desliga o modo.
• Uma store nova começa desligada. As stores que já tinham vendedores foram ligadas pela migração.
• Ligado, todo token precisa de seller_id de um vendedor da própria store (400 sem ele, 404 se não existir).
• As regras de split têm quatro níveis, e vale o primeiro que existir para a forma de pagamento: a regra com nome que o token indica em split_rule, a regra própria do vendedor (na página dele), o padrão da store (em cada forma de pagamento) e, por fim, os 10% do sistema. Tudo fica reunido em Regras de split. Uma regra com nome pode definir só algumas formas de pagamento; as demais seguem para o nível seguinte. O nome é guardado no pedido; apagar a regra depois faz os pedidos em aberto caírem no nível seguinte, e tokens novos com esse nome são recusados.
• O corpo do POST /checkout nunca decide o split: percentuais e valores enviados pelo navegador são descartados quando o pedido existe.

Como o checkout escolhe

Cada store cadastra os gateways que usa, com credenciais próprias (criptografadas com AES-GCM; a chave secreta nunca volta ao navegador, só uma máscara). Em Formas de pagamento ela liga ou desliga cartão, Pix e boleto e escolhe o gateway de cada um. O pedido público (GET /api/v1/orders/{id}) devolve payment_methods e a chave pública da store; a página mostra só essas formas, e o servidor recusa (400) qualquer outra, porque a página não é uma barreira de segurança.

• Sem credenciais próprias, a store usa as da instalação (variáveis de ambiente ou a tabela de configurações da API), como sempre foi. Se não houver nenhuma, o checkout avisa que a loja não aceita pagamentos.
• Desativar o gateway numa store tira as formas dele do checkout, mesmo que a instalação tenha chaves.
• A store de um pagamento vem sempre do pedido no banco, nunca do corpo da requisição: um pagamento nunca é assinado com a chave de outra store.

A aplicação separa a entrada (handlers), as regras de negócio (serviços) e a infraestrutura (cliente do Pagar.me, banco, Temporal). Os handlers só validam e coordenam; os serviços concentram as regras.

O servidor lê estas variáveis na inicialização. Use o .env.example do repositório como ponto de partida.

• DATABASE_URL

  String de conexão do PostgreSQL.

  postgres://user:pass@host:5432/db

• TEMPORAL_ADDR

  Endereço do servidor Temporal usado pelo worker e pelo cliente de workflows.

  localhost:7233

• TEMPORAL_NAMESPACE

  Namespace do Temporal.

  default

• TEMPORAL_API_KEY

  Chave de API do Temporal (Temporal Cloud). Opcional em ambiente local.

• USE_TEMPORAL_FOR_ACTIONS

  true: o checkout inicia o CheckoutWorkflow e responde 202 (processing). false: processa de forma síncrona.

  false

• ENABLE_SPLIT_MARKETPLACE

  Padrão do modo marketplace para pedidos sem store e para stores sem registro próprio. Cada store liga ou desliga o seu em Admin → Integrações.

  true

• JWT_SECRET

  Segredo dos tokens JWT de clientes.

  um-segredo-forte

• SELLER_JWT_SECRET

  Segredo dos tokens de convite e das sessões de seller/admin.

  outro-segredo-forte

• PAGARME_SECRET_KEY

  Chave secreta da API do Pagar.me v5.

  sk_test_…

• PAGARME_PUBLIC_KEY

  Chave pública usada na tokenização do cartão no navegador. Lida primeiro da tabela de configurações e, se ausente, desta variável.

  pk_test_…

• PAGARME_WEBHOOK_SECRET

  Segredo do webhook configurado no Pagar.me (reservado para validação de assinatura).

• PAGARME_BASE_URL

  URL base da API do Pagar.me.

  https://api.pagar.me/core/v5

• SETTINGS_ENCRYPTION_KEY

  Chave AES-GCM que criptografa os valores sensíveis das configurações e as credenciais dos gateways das stores. 16, 24 ou 32 caracteres são usados como estão; qualquer outro tamanho passa por SHA-256.

  32 caracteres

• PORT

  Porta HTTP do servidor.

  8080

DATABASE_URL=postgres://postgres:postgres@localhost:5432/checkout_db?sslmode=disable
USE_TEMPORAL_FOR_ACTIONS=false
ENABLE_SPLIT_MARKETPLACE=true
JWT_SECRET=your-customer-jwt-secret
SELLER_JWT_SECRET=your-seller-jwt-secret
PAGARME_SECRET_KEY=sk_test_...
PAGARME_PUBLIC_KEY=pk_test_...
PAGARME_BASE_URL=https://api.pagar.me/core/v5
PORT=8080

O pedido é assinado com HS256 usando o ORDER_SECRET da store. O servidor localiza o segredo pela store informada no token, verifica a assinatura e a expiração e só então cria o pedido. Os claims estão descritos em O token.

Boas práticas

A administração acontece pelo mesmo binário do servidor. Em desenvolvimento, go run main.go <comando> é equivalente, e as tarefas mise run db:migrate, db:seed-demo e db:add-admin são atalhos.

Comandos essenciais

./bin/server                          # inicia a API (padrão)
./bin/server migrate up               # aplica as migrações
./bin/server migrate down             # reverte TODAS as migrações (destrutivo)
./bin/server seed-demo                # cria store, seller e admin de demonstração
./bin/server add-admin <email> <senha> <store_id>
./bin/server keygen [--save]          # gera 32 bytes aleatórios (hex) para criptografia

Gestão de stores

Cada store possui um ORDER_SECRET, que assina os pedidos (o JWT do checkout). A CLI também gera um SELLER_SECRET e o guarda junto, mas os convites de onboarding são assinados com a variável SELLER_JWT_SECRET.

# Provisiona as chaves da store (aleatórias se omitidas)
./bin/server store create <store_id> [--order-secret s1] [--seller-secret s2]

# Gera um JWT de teste para o checkout
./bin/server store jwt <store_id> <amount_cents> "<item_name>"

Store 'MINHA_STORE' created successfully!
--------------------------------------------------
ORDER_SECRET:  9f2c…d41a
SELLER_SECRET: 51be…07c3
--------------------------------------------------
Keep these secrets safe. They are stored in the database.

Os segredos ficam no banco. O ORDER_SECRET pode ser consultado e renovado em Admin → Integrações; stores criadas pelo painel já nascem com ele. A CLI também registra a store e o vínculo do admin.