Criar Pagamento

📌 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

Parâmetro	Tipo	Obrigatório	Descrição
`storeId`	string	✅	ID da loja

🧍 Body (JSON)

Campo	Tipo	Obrigatório	Regras
`name`	string	✅	3–50 caracteres
`email`	string	✅	e-mail válido, 12–100 caracteres
`cpf`	string	❌	até 24 caracteres
`gateway`	string	✅	ver gateways suportados, até 50 caracteres
`coupon`	string	❌	código do cupom, aceita null ou vazio, até 32 caracteres
`metadata`	object	❌	objeto livre
`items`	object[]	✅	ao menos 1 item

🧩 items[]

Campo	Tipo	Obrigatório	Regras
`productId`	string	✅	ID do produto
`quantity`	number	✅	mínimo 1, máximo 50

💳 Gateways suportados

O campo gateway segue o padrão <PROVEDOR>_ORDER_<MÉTODO>:

Valor	Provedor	Método
`MERCADOPAGO_ORDER_PIX`	Mercado Pago	PIX
`MERCADOPAGO_ORDER_CARD`	Mercado Pago	Cartão
`MERCADOPAGO_ORDER_BOLETO`	Mercado Pago	Boleto
`MERCADOPAGO_ORDER_SALDO`	Mercado Pago	Saldo
`ASAAS_ORDER_PIX`	Asaas	PIX
`ASAAS_ORDER_CARD`	Asaas	Cartão
`ASAAS_ORDER_BOLETO`	Asaas	Boleto

Nota: o gateway precisa estar ativo na loja e com credenciais configuradas. A loja só recebe os métodos que habilitou nas credenciais (paymentMethods).

💳 Parcelamento no cartão

Para cobrar cartão em parcelas, informe o número de parcelas em metadata.gateway.card.installmentCount:

{
  "metadata": {
    "gateway": {
      "card": {
        "installmentCount": 6
      }
    }
  }
}

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:

Status	Código	Quando
`400`	`INVALID_INSTALLMENT_COUNT`	`installmentCount` inválido (< 1 ou não inteiro)
`400`	`MAX_INSTALLMENTS_EXCEEDED`	`installmentCount` acima do `maxInstallments` da loja

💳 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:

{
  "metadata": {
    "card": {
      "creditCardToken": "TOKEN_GERADO_NO_FRONTEND"
    },
    "gateway": { "card": { "installmentCount": 6 } }
  }
}

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).
Erro da gateway (ex.: token inválido) retorna 500 GATEWAY_ERROR com o corpo do provedor — nenhuma cobrança é criada.

✅ Exemplo de requisição

curl -X POST "https://api.cabrapi.com.br/stores/STORE_ID/payments" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "[email protected]",
    "gateway": "MERCADOPAGO_ORDER_PIX",
    "coupon": "BEMVINDO10",
    "items": [
      { "productId": "PRODUCT_ID", "quantity": 1 }
    ]
  }'

💳 Exemplo com Asaas (PIX)

curl -X POST "https://api.cabrapi.com.br/stores/STORE_ID/payments" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "[email protected]",
    "cpf": "12345678909",
    "gateway": "ASAAS_ORDER_PIX",
    "items": [
      { "productId": "PRODUCT_ID", "quantity": 1 }
    ]
  }'

💳 Exemplo com Cartão parcelado (6x, Mercado Pago)

curl -X POST "https://api.cabrapi.com.br/stores/STORE_ID/payments" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "[email protected]",
    "cpf": "12345678909",
    "gateway": "MERCADOPAGO_ORDER_CARD",
    "metadata": {
      "gateway": { "card": { "installmentCount": 6 } }
    },
    "items": [
      { "productId": "PRODUCT_ID", "quantity": 1 }
    ]
  }'

🧩 Snippet (cURL)

curl -s -X POST "https://api.cabrapi.com.br/stores/STORE_ID/payments" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "[email protected]",
    "gateway": "MERCADOPAGO_ORDER_PIX",
    "coupon": "BEMVINDO10",
    "items": [
      { "productId": "PRODUCT_ID", "quantity": 1 }
    ]
  }'

📦 Respostas

201 — Pagamento via gateway (PIX / Mercado Pago)

{
  "status": true,
  "data": {
    "service": {
      "type": "MERCADOPAGO",
      "method": "MERCADOPAGO_ORDER_PIX",
      "payment": "PIX"
    },
    "payment": {
      "uuid": "8cf7de6e-4c92-4baf-b978-2f9195f2e0e2",
      "init_point": "https://www.mercadopago.com.br/...",
      "qr_code": {
        "image": "base64...",
        "base_64": "00020126..."
      }
    }
  }
}

201 — Pagamento via gateway (Cartão / Mercado Pago)

{
  "status": true,
  "data": {
    "service": {
      "type": "MERCADOPAGO",
      "method": "MERCADOPAGO_ORDER_CARD",
      "payment": "CARD"
    },
    "payment": {
      "uuid": "8cf7de6e-4c92-4baf-b978-2f9195f2e0e2",
      "init_point": "https://www.mercadopago.com.br/checkout/..."
    }
  }
}

201 — Pagamento via gateway (PIX / Asaas)

{
  "status": true,
  "data": {
    "service": {
      "type": "ASAAS",
      "method": "ASAAS_ORDER_PIX",
      "payment": "PIX"
    },
    "payment": {
      "uuid": "8cf7de6e-4c92-4baf-b978-2f9195f2e0e2",
      "id": "pay_edji4wdwby9402g3",
      "status": "PENDING",
      "environment": "SANDBOX",
      "init_point": "https://www.asaas.com/i/edji4wdwby9402g3",
      "invoiceUrl": "https://www.asaas.com/i/edji4wdwby9402g3",
      "copyPastePix": "00020126...",
      "pixQrCode": {
        "encodedImage": "base64...",
        "payload": "00020126...",
        "expirationDate": "2026-09-08"
      }
    }
  }
}

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

{
  "status": true,
  "data": {
    "service": {
      "type": "FREE_PAYMENT",
      "method": "FREE_PAYMENT",
      "payment": "FREE_PAYMENT"
    },
    "payment": {
      "uuid": "8cf7de6e-4c92-4baf-b978-2f9195f2e0e2"
    }
  }
}

⚠️ Erros

Status	Código	Descrição
`400`	`INVALID_DATA`	Body inválido ou campo ausente
`400`	`INVALID_INSTALLMENT_COUNT`	Número de parcelas inválido (< 1 ou não inteiro)
`400`	`MAX_INSTALLMENTS_EXCEEDED`	`installmentCount` acima do `maxInstallments` da loja
`400`	`GATEWAY_NOT_ENABLED`	Gateway não habilitado na loja
`400`	`INVALID_COUPON`	Cupom não existe ou não aplicável aos produtos
`400`	`COUPON_EXPIRED`	Cupom expirado ou sem usos
`400`	`OUT_OF_STOCK`	Estoque insuficiente
`400`	`PRODUCT_DISABLED`	Produto desabilitado para compra
`404`	`STORE_NOT_FOUND`	Loja não encontrada
`404`	`PRODUCT_NOT_FOUND`	Produto não encontrado
`500`	`GATEWAY_ERROR`	Erro no provedor de pagamento
`500`	`INTERNAL_SERVER_ERROR`	Erro interno

Introdução

Lojas

Webhooks

Categorias

Produtos

Cupons

Pagamentos

Afiliados

Pagina da loja

Criar Pagamento

📌 Endpoint

🔐 Autenticação

🧾 Parâmetros de rota

🧍 Body (JSON)

🧩 items[]

💳 Gateways suportados

💳 Parcelamento no cartão

💳 Cartão transparente (tokenizado)

✅ Exemplo de requisição

💳 Exemplo com Asaas (PIX)

💳 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)

201 — Pagamento gratuito

⚠️ Erros

​📌 Endpoint

​🔐 Autenticação

​🧾 Parâmetros de rota

​🧍 Body (JSON)

​🧩 items[]

​💳 Gateways suportados

​💳 Parcelamento no cartão

​💳 Cartão transparente (tokenizado)

​✅ Exemplo de requisição

​💳 Exemplo com Asaas (PIX)

​💳 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)

​201 — Pagamento gratuito

​⚠️ Erros

📌 Endpoint

🔐 Autenticação

🧾 Parâmetros de rota

🧍 Body (JSON)

🧩 items[]

💳 Gateways suportados

💳 Parcelamento no cartão

💳 Cartão transparente (tokenizado)

✅ Exemplo de requisição

💳 Exemplo com Asaas (PIX)

💳 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)

201 — Pagamento gratuito

⚠️ Erros