Pagamentos
Criar Pagamento
Aprenda a criar pagamentos usando o endpoint POST /stores//payments.
POST
Create payment
📌 Endpoint
POST /stores/{storeId}/payments
Cria um pagamento para um ou mais produtos da loja.
🔐 Autenticação
Rota pública. A assinatura ativa do dono da loja é validada internamente.🧾 Parâmetros de rota
🧍 Body (JSON)
🧩 items[]
💳 Gateways suportados
O campogateway segue o padrão <PROVEDOR>_ORDER_<MÉTODO>:
Nota: o gateway precisa estar ativo na loja e com credenciais configuradas. A loja só recebe os métodos que habilitou nas credenciais (paymentMethods).
URLs de retorno do Stripe
Para criar uma sessão do Stripe Checkout, você pode enviarsuccessUrl e cancelUrl (válidas com http:// ou https://) dentro de metadata. Quando omitidas, a API usa o domínio configurado na loja (store.Domain) ou faz fallback para a URL base da plataforma (SiteBaseURL) caso store.Domain esteja vazio.
💳 Parcelamento no cartão
Para cobrar cartão em parcelas, informe o número de parcelas emmetadata.gateway.card.installmentCount:
- O número escolhido é o que vale — deve ficar entre
1e omaxInstallmentsconfigurado no gateway da loja (máximo 12). Se ultrapassar o limite, a API recusa com400 MAX_INSTALLMENTS_EXCEEDED; se for inválido (< 1 ou não inteiro),400 INVALID_INSTALLMENT_COUNT. - Quando o lojista configurou faixas de parcelas (
installmentFees) no gateway, a taxa da faixa que contém oinstallmentCountsubstitui a taxa plana defees.card— aplicada uma única vez sobre o total, que é então dividido igualmente pelas parcelas. Ex.: faixas 1x0% + R$ 0, 2–6x3,49% + R$ 0,49, 7–12x3,99% + R$ 0,49. - Aplicação na gateway: as gateways de cartão suportadas (Asaas e Mercado Pago) recebem o número de parcelas escolhido e dividem o total (taxa já embutida) igualmente nas N× em todos os fluxos — fatura hospedada ou cartão tokenizado. No Mercado Pago o checkout é limitado ao número escolhido (
max_installments). - Sem o campo, o cartão é cobrado à vista (1x) com a taxa plana de
fees.card(no Mercado Pago, até omaxInstallmentsdo lojista). - O
installmentCountfica registrado no pagamento emmetadata.gateway.card.installmentCount(junto degateway.FeePercentage/gateway.FeeAmount), permitindo rastrear em quantas vezes a venda foi parcelada. - Erros de parcelamento retornam somente o código (sem
message), seguindo o padrão da rota:
💳 Cartão transparente (tokenizado)
Para cobrar o cartão sem redirecionar o comprador, o frontend tokeniza os dados no navegador (SDK público da gateway, com a public key) e envia só o token emmetadata.card — os dados do cartão nunca passam pela API:
- O token também é aceito em
metadata.gateway.card.creditCardToken. As parcelas continuam emmetadata.gateway.card.installmentCount(validado contra omaxInstallmentsda loja). - Sem token, nada muda: o fluxo cai no checkout hospedado (redirect) como antes.
- Mercado Pago: com token, a API cobra direto (
POST /v1/payments) e responde seminit_point— vempaymentId,statusestatusDetail; o status final é acompanhado pela fila de verificação (consulta o payment na gateway). Opcional:paymentMethodIdeissuerId(o SDK do MP informa ambos). - Asaas: com token (
creditCardToken, oucreditCard+creditCardHolderInfo), cobra direto; sem token, gera a fatura hospedada (invoiceUrl/init_point). - EFI Bank: pagamentos com cartão exigem
metadata.gateway.card.payment_tokengerado pelo SDK frontend da EFI emetadata.gateway.card.phone_number. - Erro da gateway (ex.: token inválido) retorna
502 GATEWAY_ERRORcom o campoerrorcontendo a resposta do provedor — nenhuma cobrança é criada.
✅ Exemplo de requisição
MERCADOPAGO_ORDER_BOLETO para boleto ou MERCADOPAGO_ORDER_SALDO para saldo. Os dois usam o mesmo body do exemplo de PIX; basta trocar o campo gateway.
💳 Exemplo com Asaas (PIX)
gateway por ASAAS_ORDER_BOLETO. Para cartão hospedado, use ASAAS_ORDER_CARD; para cobrança transparente, envie também o token de cartão e os dados do titular conforme a seção Cartão transparente (tokenizado).
💳 Exemplo com EFI Bank (PIX)
EFI_BANK_ORDER_BOLETO no campo gateway. O cartão EFI exige tokenização no frontend e telefone do comprador:
💳 Exemplo com Stripe Checkout (PIX)
gateway por STRIPE_ORDER_CARD ou STRIPE_ORDER_BOLETO. Se successUrl ou cancelUrl forem omitidas, a API usa o domínio da loja (store.Domain) ou SiteBaseURL quando a loja não possui domínio configurado.
💳 Exemplo com Cartão parcelado (6x, Mercado Pago)
🧩 Snippet (cURL)
📦 Respostas
201 — Pagamento via gateway (PIX / Mercado Pago)
201 — Pagamento via gateway (Cartão / Mercado Pago)
201 — Pagamento via gateway (PIX / Asaas)
Para Asaas, acompanhe ostatus/idviametadata.gatewayno filtro de pagamentos (fila de verificação consulta a gateway diretamente). A fatura hospedada (invoiceUrl/init_point) permite ao comprador pagar por PIX, cartão ou boleto sem tokenização.
201 — Pagamento gratuito
200 — Replay de idempotência (Idempotency-Key / idempotencyKey)
Quando a requisição reutiliza uma chave já processada na loja (via header Idempotency-Key ou campo idempotencyKey no body), a API não cria um novo pagamento e retorna HTTP 200 com o payload original salvo da criação:
Se a resposta original ainda não estiver gravada, o fallback200retorna{"status": true, "data": {"payment": {"uuid": "...", "status": "..."}}}.
⚠️ Erros
Nos erros400 OUT_OF_STOCK,400 PRODUCT_DISABLEDe404 PRODUCT_NOT_FOUND, a resposta inclui o campoproductIdidentificando o item ({"code": "...", "productId": "..."}).
Cabeçalhos
Corpo
application/json
Charge details (items, customer, gateway).