Pular para o conteúdo principal
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 campo gateway 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 enviar successUrl 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 em metadata.gateway.card.installmentCount:
  • O número escolhido é o que vale — deve ficar entre 1 e o maxInstallments configurado no gateway da loja (máximo 12). Se ultrapassar o limite, a API recusa com 400 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 o installmentCount substitui a taxa plana de fees.card — aplicada uma única vez sobre o total, que é então dividido igualmente pelas parcelas. Ex.: faixas 1x 0% + R$ 0, 2–6x 3,49% + R$ 0,49, 7–12x 3,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é o maxInstallments do lojista).
  • O installmentCount fica registrado no pagamento em metadata.gateway.card.installmentCount (junto de gateway.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 em metadata.card — os dados do cartão nunca passam pela API:
  • O token também é aceito em metadata.gateway.card.creditCardToken. As parcelas continuam em metadata.gateway.card.installmentCount (validado contra o maxInstallments da 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 sem init_point — vem paymentId, status e statusDetail; o status final é acompanhado pela fila de verificação (consulta o payment na gateway). Opcional: paymentMethodId e issuerId (o SDK do MP informa ambos).
  • Asaas: com token (creditCardToken, ou creditCard + creditCardHolderInfo), cobra direto; sem token, gera a fatura hospedada (invoiceUrl / init_point).
  • EFI Bank: pagamentos com cartão exigem metadata.gateway.card.payment_token gerado pelo SDK frontend da EFI e metadata.gateway.card.phone_number.
  • Erro da gateway (ex.: token inválido) retorna 502 GATEWAY_ERROR com o campo error contendo a resposta do provedor — nenhuma cobrança é criada.

✅ Exemplo de requisição

No Mercado Pago, use 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)

Para boleto no Asaas, use o mesmo formato e troque 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)

Para boleto, use 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)

Para cartão ou boleto no Stripe, troque o valor de 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 o status / id via metadata.gateway no 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 fallback 200 retorna {"status": true, "data": {"payment": {"uuid": "...", "status": "..."}}}.

⚠️ Erros

Nos erros 400 OUT_OF_STOCK, 400 PRODUCT_DISABLED e 404 PRODUCT_NOT_FOUND, a resposta inclui o campo productId identificando o item ({"code": "...", "productId": "..."}).

Cabeçalhos

Idempotency-Key
string

Optional idempotency key to prevent duplicate charges.

Maximum string length: 255

Parâmetros de caminho

storeId
string
obrigatório
Required string length: 1 - 50

Corpo

application/json

Charge details (items, customer, gateway).

name
string
obrigatório
Required string length: 3 - 50
email
string<email>
obrigatório
Required string length: 12 - 100
gateway
string
obrigatório
Required string length: 1 - 50
items
object[]
obrigatório
Minimum array length: 1
cpf
string | null
Maximum string length: 24
coupon
string | null
Maximum string length: 32
idempotencyKey
string | null
Maximum string length: 255
metadata
object | null

Resposta

Idempotent replay of an already-created payment.

data
object
obrigatório
status
boolean
Exemplo:

true