Checkout pela API

Com a API, o seu site mostra os produtos, monta o carrinho e fecha o pedido. A cobrança é criada no gateway conectado na loja e o dinheiro cai direto na sua conta do gateway, como numa venda pela vitrine. Entregas, e-mails ao cliente, cupons, ofertas e proteção de checkout funcionam do mesmo jeito.

Antes de começarCopiar link da seção

• Um gateway conectado e uma rota para cada forma de pagamento que você vai oferecer, em Configurações › Gateways. Teste primeiro com o gateway em Sandbox. Veja Gateways de pagamento.
• Pelo menos um produto publicado, com preço ativo.
• Uma chave publicável com os escopos Catálogo (leitura) e Carrinho e checkout (catalog:read e checkout:write). Veja Autenticação.

Visão geral do fluxoCopiar link da seção

1. GET /products e GET /products/{productId}: mostre os produtos e escolha o preço (priceId).
2. POST /carts: crie o carrinho e guarde o id e o token.
3. /carts/{cartId}/**: adicione itens, altere quantidades e aplique cupom, sempre com o cabeçalho X-Cart-Token.
4. GET /payment-methods: mostre as formas de pagamento que a loja aceita e carregue o SDK do gateway de cartão com a configuração pública.
5. POST /checkout: feche o pedido com os dados do comprador e a forma de pagamento.
6. Mostre o Pix ou o boleto, conclua a etapa do cartão quando o gateway pedir e leve o comprador à página do pedido. Se o pagamento for recusado, pague de novo com POST /orders/{orderId}/payments.
7. No seu servidor, receba order.paid por webhook para saber que o pagamento foi confirmado.

const MINEPAG_PUBLISHABLE_KEY = 'pk_…';
const api = (path, init = {}) =>
  fetch(`https://minepag.com.br/api/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${MINEPAG_PUBLISHABLE_KEY}`, 'Content-Type': 'application/json', ...init.headers }
  }).then(async response => {
    const body = await response.json();
    if (!response.ok) throw Object.assign(new Error(body.error.message), { code: body.error.code, issues: body.error.issues });
    return body;
  });

const { data: products } = await api('/products?limit=24');

const { data: cart } = await api('/carts', {
  method: 'POST',
  body: JSON.stringify({
    items: [{ priceId: '0193b7c2-3c11-7a44-9b1e-0f1a2b3c4d05', quantity: 1 }],
    context: { utmSource: 'instagram', utmCampaign: 'lancamento' }
  })
});

localStorage.setItem('minepag:cart', JSON.stringify({ id: cart.id, token: cart.token }));

const saved = JSON.parse(localStorage.getItem('minepag:cart'));
const { data: updated } = await api(`/carts/${saved.id}/coupon`, {
  method: 'PUT',
  headers: { 'X-Cart-Token': saved.token },
  body: JSON.stringify({ code: 'BEMVINDO10' })
});

const idempotencyKey = crypto.randomUUID();
// Guarde o momento em que o comprador marcou "Li e aceito os termos" no seu checkout.
const termsAcceptedAt = new Date();

const { data: checkout } = await api('/checkout', {
  method: 'POST',
  headers: { 'X-Cart-Token': saved.token, 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify({
    cartId: saved.id,
    buyer: { name: 'Steve Silva', email: 'steve@exemplo.com.br', phone: '11987654321', document: '12345678909' },
    payment: { method: 'pix' },
    marketingConsent: false,
    termsAcceptedAt: termsAcceptedAt.toISOString()
  })
});

{
  "data": {
    "order": {
      "id": "0193b7c2-5b2f-7d66-8e30-2b3c4d5e6f02",
      "number": 1042,
      "status": "pending",
      "paymentStatus": "pending",
      "subtotal": 4990,
      "discountTotal": 0,
      "total": 4990,
      "expiresAt": "2026-10-12T15:15:00.000Z"
    },
    "payment": {
      "id": "0193b7c2-5b40-7d66-8e30-2b3c4d5e6f07",
      "method": "pix",
      "status": "pending",
      "amount": 4990,
      "instructions": {
        "method": "pix",
        "copyPaste": "00020101021226…6304ABCD",
        "qrCodeImage": "data:image/png;base64,iVBORw0KGgo…",
        "expiresAt": "2026-10-12T15:00:00.000Z"
      },
      "clientAction": { "kind": "none" },
      "failureReason": null
    },
    "accessToken": "eyJvcmRlcklkIjoi…",
    "orderUrl": "https://minha-loja.minepag.app/order/0193b7c2-5b2f-7d66-8e30-2b3c4d5e6f02?token=…"
  },
  "meta": { "requestId": "5b0f7a52-0d8e-4b51-9a57-1f0c6b7e2d10" }
}

Pagamento com cartãoCopiar link da seção

O número do cartão nunca passa pela MinePag nem pelo seu servidor. O formulário do cartão roda no navegador com o SDK do gateway, que devolve um token. Esse token vai em payment.card, com o provider do gateway que atende cartão na loja (veja em Configurações › Gateways). Token de outro gateway é recusado com 422 validation_failed em payment.card.

As chaves públicas do gateway (Public Key, chave publicável, identificador de conta) ficam na sua conta do gateway. Use as do mesmo ambiente (Sandbox ou Produção) da conexão na MinePag.

{ "provider": "stripe", "confirmationTokenId": "ctoken_1Q…" }

Erros comuns no checkoutCopiar link da seção

Pagamento recusado e nova tentativaCopiar link da seção

Quando o gateway recusa o pagamento, POST /checkout responde 402 payment_declined. O pedido já existe e continua aguardando pagamento: error.details traz o mesmo objeto da resposta de sucesso, com order, payment (status: "failed" e o motivo em failureReason), accessToken e orderUrl.

Para pagar de novo, peça outro cartão ou outra forma de pagamento e chame POST /orders/{orderId}/payments com o accessToken no cabeçalho X-Order-Token:

curl -X POST https://minepag.com.br/api/v1/orders/$ORDER_ID/payments \
  -H "Authorization: Bearer $MINEPAG_PUBLISHABLE_KEY" \
  -H "X-Order-Token: $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "buyer": { "name": "Ana Souza", "email": "ana@example.com" }, "payment": { "method": "pix" } }'

A resposta tem o mesmo formato do checkout. Cada tentativa é um novo pagamento do mesmo pedido; outra recusa responde 402 de novo. A rota responde 409 conflict se ainda houver um pagamento em andamento e 409 order_not_payable se o pedido já foi pago, cancelado ou expirou. Se preferir, leve o comprador para orderUrl: a página do pedido também oferece a nova tentativa.

Gateway fora do ar e nova tentativaCopiar link da seção

Quando o gateway não responde, POST /checkout responde 502 payment_provider_unavailable. O carrinho já virou pedido, mas a cobrança não foi criada: error.details traz order, payment (status: "pending" e instructions: null), accessToken e orderUrl.

{
  "data": null,
  "error": {
    "code": "payment_provider_unavailable",
    "message": "O gateway de pagamento não respondeu. O pedido #1042 foi criado e continua aguardando pagamento: abra o pedido para tentar de novo.",
    "details": {
      "order": { "id": "0193b7c2-5b2f-7d66-8e30-2b3c4d5e6f02", "number": 1042, "status": "pending", "paymentStatus": "pending", "total": 4990 },
      "payment": { "id": "0193b7c2-5b40-7d66-8e30-2b3c4d5e6f07", "method": "pix", "status": "pending", "instructions": null },
      "accessToken": "eyJvcmRlcklkIjoi…",
      "orderUrl": "https://minha-loja.minepag.app/order/0193b7c2-5b2f-7d66-8e30-2b3c4d5e6f02?token=…"
    },
    "requestId": "5b0f7a52-0d8e-4b51-9a57-1f0c6b7e2d10"
  }
}

Para tentar de novo, escolha um caminho:

1. Mesma forma de pagamento: repita POST /checkout com a mesma Idempotency-Key e o mesmo corpo, com espera crescente (ex.: 1 s, 2 s, 4 s). A resposta de erro 5xx não fica guardada, então a repetição executa de verdade: a MinePag encontra o pedido já criado e cria a cobrança que faltou. A resposta é 200 com o pedido e as instruções de pagamento. A cobrança vai ao gateway com a mesma chave de idempotência, sem risco de cobrar duas vezes.
2. Outra forma de pagamento, ou mais tarde: chame POST /orders/{orderId}/payments com o accessToken no cabeçalho X-Order-Token, como na recusa acima. Com a mesma forma de pagamento, a cobrança é criada no pagamento que ficou pendente; com outra, esse pagamento é cancelado e uma nova tentativa começa. Também dá para levar o comprador para orderUrl.

Não monte outro carrinho nem use outra Idempotency-Key no mesmo carrinho: a resposta seria 409 cart_already_checked_out. Se o gateway continuar fora do ar, as duas rotas respondem 502 de novo, com os mesmos details.

A lista completa está em Erros da API.

TestarCopiar link da seção

1. Conecte o gateway em Sandbox. As formas que ele aceita entram na coluna Equipe testando · Sandbox da seção Checkout, sem mexer nas rotas de Produção.
2. Faça uma compra completa com os dados de teste do gateway, usando a chave secreta no seu servidor e payment.environment: "sandbox". Com a chave publicável, as formas de pagamento em Sandbox não aparecem em GET /payment-methods e o checkout em Sandbox responde payment_method_unavailable, para nenhum cliente cair num gateway de teste.
3. Confira o pedido em Vendas › Pedidos e as entregas em Entregas.
4. Pedidos em Sandbox não contam na sua fatura da MinePag.