Campos de checkout
Peça ao cliente o nick do Minecraft, o usuário do Discord ou outras informações na hora da compra, com validação pronta.
Campos de checkout são perguntas que o cliente responde ao comprar um produto. O checkout já pede nome e e-mail; os campos servem para o que a entrega precisa, como o nick do Minecraft, ou para um briefing de serviço.
Eles ficam na aba Checkout do produto, no bloco Campos no checkout. As respostas ficam guardadas no pedido e aparecem no painel, na API e nos webhooks.
Tipos de campo
Cada tipo tem validação própria, feita no servidor. Não é possível usar expressões regulares próprias.
| Tipo | O que aceita |
|---|---|
| Nick do Minecraft | De 3 a 16 caracteres com letras, números e _. Nick de Bedrock começa com ponto (.Steve). |
| Usuário do Discord | Nome de usuário novo do Discord, de 2 a 32 caracteres, sem # e sem espaços. O @ inicial é removido. |
| Texto curto | Uma linha, com mínimo e máximo de caracteres opcionais (até 255 por padrão). |
| Texto longo | Várias linhas, para instruções ou briefing (até 2.000 caracteres por padrão). |
| Endereço de e-mail válido. | |
| Telefone | Telefone com DDD. |
| CPF ou CNPJ | Documento validado pelos dígitos verificadores. Fica guardado só com os números. |
| Número | Número inteiro, com mínimo e máximo opcionais. |
| Link | Endereço que começa com https://. |
| Data | Dia, mês e ano. |
| Caixa de seleção | Sim ou não, como um aceite de termos. Quando obrigatória, precisa estar marcada. |
| Escolha única | O cliente escolhe uma das opções (até 50). |
| Múltipla escolha | O cliente escolhe uma ou mais opções (até 50). |
Adicionar um campo
Abra a aba Checkout
No produto, abra Checkout e clique em Adicionar campo.
Escolha o tipo e o rótulo
| Campo | Regra |
|---|---|
| Tipo | Um dos tipos da tabela acima. |
| Rótulo | O que o cliente lê, até 120 caracteres. Ex.: "Seu nick no Minecraft". |
| Chave | Identifica o campo na API e nos webhooks. Gerada a partir do rótulo (Seu nick no Minecraft vira seu_nick_no_minecraft). Letras minúsculas, números e _, começando por letra, até 64 caracteres. Única no produto. |
| Texto de ajuda | Opcional, até 300 caracteres, abaixo do campo. |
| Exemplo dentro do campo | Opcional, até 120 caracteres. |
| Mínimo e máximo | Caracteres (textos) ou valores (número), quando fizer sentido. |
| Opções | Em escolha única e múltipla escolha. |
| Pedir em | Todos os preços ou um preço específico. |
Defina se é obrigatório
Com Obrigatório ligado, o cliente não fecha a compra sem responder.
Teste a validação
Use Testar validação para digitar um valor como o cliente digitaria e ver a mensagem de erro, se houver. Depois, clique em Adicionar campo.
Arraste os campos para mudar a ordem em que aparecem no checkout.
Nick do Minecraft
Produtos do tipo Item Minecraft já nascem com o campo Seu nick no Minecraft (chave nick), obrigatório.
Não remova o nick se os comandos usam {player}
Se um benefício de Comando no Minecraft usa {player} ou {uuid}, todo preço em que ele vale precisa de um campo obrigatório de nick.
Sem isso, o produto não pode ser publicado. Em produto já publicado, a remoção do campo é recusada.
O nick digitado é o jogador que recebe os comandos, o que permite comprar de presente para outra pessoa. Veja Benefícios.
Remover um campo
Ao remover, as novas compras deixam de pedir a informação. Pedidos antigos mantêm o que o cliente respondeu.
Enviar as respostas pela API
No checkout pela API, envie as respostas em checkoutFields de cada item do carrinho, usando a chave de cada campo. Todos os valores são texto:
| Tipo | Formato do valor |
|---|---|
| Caixa de seleção | "true" ou "false" |
| Múltipla escolha | Opções separadas por vírgula: "Opção A, Opção B" |
| Data | "AAAA-MM-DD", como "2026-10-13" |
| CPF ou CNPJ | Com ou sem pontuação; fica guardado só com os números |
| Demais tipos | O texto digitado |
Os campos de cada produto aparecem em checkoutFields na rota Consultar produto, com key, type, required, priceId e as regras.
const response = await fetch('https://minepag.com.br/api/v1/carts', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MINEPAG_PUBLISHABLE_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'cliente@exemplo.com',
items: [{ priceId: 'ID_DO_PRECO', quantity: 1, checkoutFields: { nick: 'Steve' } }]
})
});
const { data } = await response.json();
// Guarde data.token: ele vai no cabeçalho X-Cart-Token nas próximas chamadas do carrinho.
console.log(data.token, data.issues);Respostas inválidas ou campos obrigatórios em branco não impedem criar o carrinho: eles aparecem em issues, com o código checkout_fields, e no item, em checkoutFields[].value. O checkout só fecha depois de corrigidos, e a resposta de erro traz a mensagem de cada item em issues. Para corrigir, altere o item com Alterar item do carrinho.
O fluxo completo está em Checkout pela API.