Checkout

Criar sessão de checkout

POST/v1/checkout-sessionscharges:writeNOVO

Sessão de checkout para integração servidor a servidor. Com o checkout do comprador liberado, checkout_available é true e checkout_url é o link da página Mainum para onde você envia o comprador: ele informa só o e-mail e paga por Pix. Enquanto o checkout do comprador não estiver liberado, ou depois que a sessão expirar, checkout_available é false e checkout_url é null. OPEN indica apenas uma sessão ainda não expirada, nunca pagamento confirmado: confirme pelo evento charge.paid (metadata.checkout_session_id) ou consultando a cobrança, nunca pelo redirecionamento. Não envie sua chave de API ao navegador. A criação não reserva saldo/estoque nem congela tarifa financeira; preços e limites da conta são validados quando o comprador inicia o Pix. Operações de loja ainda não são aceitas. A mesma Idempotency-Key e corpo recuperam a sessão original (inclusive expirada), sem renovar prazo; outro corpo ou external_id reutilizado com nova chave retorna 409.

Envie sempre o cabeçalho Idempotency-Key. Se a conexão cair, repita a chamada com a mesma chave: você recebe o mesmo recurso, nunca um segundo. Como repetir com segurança

Cabeçalhos

Authorizationstringobrigatório

Bearer seguido da sua chave: gw_test_ em teste, gw_live_ em produção.

Idempotency-Keystring · 8–128obrigatório

Identificador único da tentativa, entre 8 e 128 caracteres ASCII visíveis.

Corpo da requisição

external_idstring · 1–128obrigatório

Identificador único do pedido na conta. Não reutilizar com outra chave.

operationstringopcional

GATEWAY

amount_centsinteger · 1–9007199254740991obrigatório

Soma exata dos itens; para produtos, use o preço atual do catálogo.

exemplo 2000 = R$ 20,00

itemsobject[]obrigatório

Produto do catálogo (nome/preço copiados pelo servidor) OU item avulso. Somente produtos ativos e avulsos da própria conta.

expires_in_secondsinteger · 300–86400opcional

success_urlurl · até 2048opcional

HTTPS sem usuário/senha. O comprador volta para cá alguns segundos após o pagamento confirmado; o redirecionamento não comprova pagamento.

cancel_urlurl · até 2048opcional

HTTPS sem usuário/senha. Aparece para o comprador como "Voltar para a loja".

store_iduuidopcional

Loja (painel → Lojas) cuja identidade a página de pagamento mostra: nome, cor, contato e mensagem de agradecimento. Precisa ser uma loja ativa desta conta. Não muda a tarifa.

metadataobject · até 20 chavesopcional

Dados do merchant, até 20 chaves e 2 KB; sem dados pessoais. Não publicados ao comprador nem enviados em evento nesta etapa.

Resposta 201

Sessão criada ou recuperada por idempotência, ainda sem checkout de pagamento disponível.

iduuid

Identificador da sessão. Não é credencial de acesso do comprador.

external_idstring

operationstring

GATEWAY

statusstring

Estado da validade da sessão; não é estado de pagamento.

OPENEXPIRED

amount_centsinteger · 1–9007199254740991

exemplo 2000 = R$ 20,00

currencystring

BRL

itemsobject[]

4 campos

product_iduuid | null

namestring

unit_amount_centsinteger · 1–9007199254740991

quantityinteger · 1–1000

metadataobject · até 20 chaves

Pares chave-valor seus, até 20 chaves e 2 KB. Gravados uma vez na criação e devolvidos em toda consulta e webhook. Não guarde dados pessoais aqui.

success_urlurl | null

cancel_urlurl | null

store_iduuid | null

Loja cuja identidade a página de pagamento mostra, ou null.

created_atdatetime

expires_atdatetime

checkout_availableboolean

true quando checkout_url pode ser enviado ao comprador.

checkout_urlurl | null

Link da página de pagamento Mainum desta sessão; null enquanto indisponível ou após expirar. Trate como segredo do pedido: envie só ao comprador.

Códigos de resposta

HTTP	Quando acontece
201	Sessão criada ou recuperada por idempotência, ainda sem checkout de pagamento disponível.
400	Requisição ou cursor inválido
401	Chave ausente, inválida ou sem o escopo exigido
409	Conflito de identificador externo, idempotência ou operação em andamento
422	checkout_amount_mismatch (total divergente), product_unavailable (produto de outra conta, ausente ou inativo) ou store_unavailable (loja de outra conta, pausada ou arquivada).
429	Limite de requisições excedido
503	Serviço temporariamente indisponível

Cada código de erro está explicado em Erros.

Requisição

curl -X POST "https://api.mainumpay.com/v1/checkout-sessions" \
  -H "Authorization: Bearer $MAINUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "external_id": "pedido-1001",
  "amount_cents": 2000,
  "items": [
    {
      "name": "Serviço digital",
      "unit_amount_cents": 1000,
      "quantity": 2
    }
  ],
  "expires_in_seconds": 1800
}'

Resposta

{
  "id": "0192a7c4-5b1e-7d3a-9f10-6c2e8b4d1a77",
  "external_id": "pedido-1001",
  "operation": "GATEWAY",
  "status": "OPEN",
  "amount_cents": 2000,
  "currency": "BRL",
  "items": [
    {
      "product_id": null,
      "name": "Serviço digital",
      "unit_amount_cents": 1000,
      "quantity": 2
    }
  ],
  "metadata": {},
  "success_url": null,
  "cancel_url": null,
  "store_id": null,
  "created_at": "2026-09-26T14:00:00.000Z",
  "expires_at": "2026-09-26T14:30:00.000Z",
  "checkout_available": false,
  "checkout_url": null,
  "request_id": "req_0192a7c4-5b1e-7d3a-9f10-6c2e8b4d1a78"
}

Sessão criada ou recuperada por idempotência, ainda sem checkout de pagamento disponível.