> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabrapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Pagamento

> Aprenda a criar pagamentos usando o endpoint POST /stores/{storeId}/payments.

## 📌 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 |
| `idempotencyKey` | string | ❌ | chave de idempotência; evita gerar o mesmo pagamento duas vezes, até 255 caracteres (também aceita o header `Idempotency-Key`) |
| `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 |
| `billingCycleMonths` | number | ❌ | duração do ciclo de cobrança em meses (`1` a `60`) |

***

## 💳 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 |
| `EFI_BANK_ORDER_PIX` | EFI Bank | PIX |
| `EFI_BANK_ORDER_CARD` | EFI Bank | Cartão |
| `EFI_BANK_ORDER_BOLETO` | EFI Bank | Boleto |
| `STRIPE_ORDER_PIX` | Stripe | PIX |
| `STRIPE_ORDER_CARD` | Stripe | Cartão |
| `STRIPE_ORDER_BOLETO` | Stripe | 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`).

### 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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`).
* **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

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

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)

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

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)

```bash theme={null}
curl -X POST "https://api.cabrapi.com.br/v1/stores/STORE_ID/payments" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@email.com",
    "cpf": "12345678909",
    "gateway": "EFI_BANK_ORDER_PIX",
    "items": [
      { "productId": "PRODUCT_ID", "quantity": 1 }
    ]
  }'
```

Para boleto, use `EFI_BANK_ORDER_BOLETO` no campo `gateway`. O cartão EFI exige tokenização no frontend e telefone do comprador:

```json theme={null}
{
  "name": "João Silva",
  "email": "joao@email.com",
  "cpf": "12345678909",
  "gateway": "EFI_BANK_ORDER_CARD",
  "metadata": {
    "gateway": {
      "card": {
        "payment_token": "TOKEN_GERADO_PELO_SDK_EFI",
        "phone_number": "11999999999",
        "installmentCount": 1
      }
    }
  },
  "items": [
    { "productId": "PRODUCT_ID", "quantity": 1 }
  ]
}
```

### 💳 Exemplo com Stripe Checkout (PIX)

```bash theme={null}
curl -X POST "https://api.cabrapi.com.br/v1/stores/STORE_ID/payments" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@email.com",
    "gateway": "STRIPE_ORDER_PIX",
    "metadata": {
      "successUrl": "https://loja.exemplo.com/pagamento/sucesso",
      "cancelUrl": "https://loja.exemplo.com/pagamento/cancelado"
    },
    "items": [
      { "productId": "PRODUCT_ID", "quantity": 1 }
    ]
  }'
```

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)

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

***

## 🧩 Snippet (cURL)

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

***

## 📦 Respostas

### 201 — Pagamento via gateway (PIX / Mercado Pago)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "data": {
    "service": {
      "type": "FREE_PAYMENT",
      "method": "FREE_PAYMENT",
      "payment": "FREE_PAYMENT"
    },
    "payment": {
      "uuid": "8cf7de6e-4c92-4baf-b978-2f9195f2e0e2"
    }
  }
}
```

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

```json theme={null}
{
  "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..."
      }
    }
  }
}
```

> Se a resposta original ainda não estiver gravada, o fallback `200` retorna `{"status": true, "data": {"payment": {"uuid": "...", "status": "..."}}}`.

***

## ⚠️ 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` | `COUPON_AFFILIATE_ONLY` | Cupom restrito a códigos de afiliado específicos |
| `400` | `COUPON_PAYMENT_METHOD_INVALID` | Cupom não permitido para o gateway/método escolhido |
| `400` | `COUPON_ALREADY_USED` | Cupom de uso único já utilizado por este cliente (e-mail ou CPF) |
| `400` | `COUPON_MIN_ORDER_AMOUNT` | Subtotal do pedido abaixo do valor mínimo do cupom |
| `400` | `COUPON_MIN_ITEMS_QUANTITY` | Quantidade total de itens abaixo do mínimo do cupom |
| `400` | `OUT_OF_STOCK` | Estoque insuficiente (inclui o campo `productId`) |
| `400` | `PRODUCT_DISABLED` | Produto desabilitado para compra (inclui o campo `productId`) |
| `401` | `UNAUTHENTICATED` | Falha ao identificar o proprietário da loja na validação do plano |
| `403` | `NO_ACTIVE_SUBSCRIPTION` | Assinatura do proprietário da loja inativa ou expirada |
| `404` | `STORE_NOT_FOUND` | Loja não encontrada |
| `404` | `PRODUCT_NOT_FOUND` | Produto não encontrado (inclui o campo `productId`) |
| `429` | `RATE_LIMIT_EXCEEDED` | Limite de requisições por minuto do plano excedido |
| `500` | `GATEWAY_ERROR` | Erro interno ao processar resposta da gateway (inclui o campo `error`) |
| `500` | `INTERNAL_SERVER_ERROR` | Erro interno |
| `502` | `GATEWAY_ERROR` | Erro retornado pelo provedor de pagamento (inclui o campo `error` com o corpo do provedor) |
| `503` | `SERVICE_UNAVAILABLE` | Serviço temporariamente indisponível |

> 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": "..."}`).


## OpenAPI

````yaml POST /stores/{storeId}/payments
openapi: 3.1.0
info:
  title: caBRAPI
  version: 1.0.0
servers:
  - url: https://api.cabrapi.com.br/v1
security: []
paths:
  /stores/{storeId}/payments:
    post:
      tags:
        - Payments
      summary: Create payment
      operationId: createPayment
      parameters:
        - $ref: '#/components/parameters/StoreId'
        - in: header
          name: Idempotency-Key
          required: false
          description: Optional idempotency key to prevent duplicate charges.
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        description: Charge details (items, customer, gateway).
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - gateway
                - items
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 50
                email:
                  type: string
                  format: email
                  minLength: 12
                  maxLength: 100
                cpf:
                  type: string
                  maxLength: 24
                  nullable: true
                gateway:
                  type: string
                  minLength: 1
                  maxLength: 50
                coupon:
                  type: string
                  maxLength: 32
                  nullable: true
                idempotencyKey:
                  type: string
                  maxLength: 255
                  nullable: true
                metadata:
                  nullable: true
                  type: object
                items:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                      - productId
                      - quantity
                    properties:
                      productId:
                        type: string
                        minLength: 1
                        maxLength: 50
                      quantity:
                        type: integer
                        minimum: 1
                        maximum: 50
                      billingCycleMonths:
                        type: integer
                        minimum: 1
                        maximum: 60
                        nullable: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                  status:
                    example: true
                    type: boolean
                required:
                  - data
                type: object
          description: Idempotent replay of an already-created payment.
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                  status:
                    example: true
                    type: boolean
                required:
                  - data
                type: object
          description: Payment created.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized (missing store owner or unavailable database).
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden (inactive plan or insufficient permissions).
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Resource not found.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Rate limit exceeded.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Upstream gateway or storage error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Service unavailable.
      security: []
components:
  parameters:
    StoreId:
      in: path
      name: storeId
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
  schemas:
    Error:
      properties:
        code:
          example: STORE_NOT_FOUND
          type: string
      required:
        - code
      type: object

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.