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

# Create Payment

> Learn how to create payments using the endpoint POST /stores/{storeId}/payments.

## 📌 Endpoint

`POST /stores/{storeId}/payments`

Creates a payment for one or more products of the store.

***

## 🔐 Authentication

Public route. The active subscription of the store owner is validated internally.

***

## 🧾 Route parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `storeId` | string | ✅ | Store ID |

***

## 🧍 Body (JSON)

| Field | Type | Required | Rules |
| - | - | - | - |
| `name` | string | ✅ | 3–50 characters |
| `email` | string | ✅ | valid email, 12–100 characters |
| `cpf` | string | ❌ | up to 24 characters |
| `gateway` | string | ✅ | see supported gateways, up to 50 characters |
| `coupon` | string | ❌ | coupon code, accepts null or empty, up to 32 characters |
| `metadata` | object | ❌ | free object |
| `idempotencyKey` | string | ❌ | idempotency key; prevents creating the same payment twice, up to 255 characters (the `Idempotency-Key` header is also supported) |
| `items` | object\[] | ✅ | at least 1 item |

***

### 🧩 items\[]

| Field | Type | Required | Rules |
| - | - | - | - |
| `productId` | string | ✅ | Product ID |
| `quantity` | number | ✅ | minimum 1, maximum 50 |
| `billingCycleMonths` | number | ❌ | billing cycle duration in months (`1` to `60`) |

***

## 💳 Supported gateways

The `gateway` field follows the pattern `<PROVIDER>_ORDER_<METHOD>`:

| Value | Provider | Method |
| - | - | - |
| `MERCADOPAGO_ORDER_PIX` | Mercado Pago | PIX |
| `MERCADOPAGO_ORDER_CARD` | Mercado Pago | Card |
| `MERCADOPAGO_ORDER_BOLETO` | Mercado Pago | Boleto |
| `MERCADOPAGO_ORDER_SALDO` | Mercado Pago | Balance |
| `ASAAS_ORDER_PIX` | Asaas | PIX |
| `ASAAS_ORDER_CARD` | Asaas | Card |
| `ASAAS_ORDER_BOLETO` | Asaas | Boleto |
| `EFI_BANK_ORDER_PIX` | EFI Bank | PIX |
| `EFI_BANK_ORDER_CARD` | EFI Bank | Card |
| `EFI_BANK_ORDER_BOLETO` | EFI Bank | Boleto |
| `STRIPE_ORDER_PIX` | Stripe | PIX |
| `STRIPE_ORDER_CARD` | Stripe | Card |
| `STRIPE_ORDER_BOLETO` | Stripe | Boleto |

> **Note:** the gateway needs to be **active** in the store and with credentials configured. The store only receives the methods it enabled in the credentials (`paymentMethods`).

### Stripe return URLs

To create a Stripe Checkout Session, you can send valid `http://` or `https://` `successUrl` and `cancelUrl` values inside `metadata`. When omitted, the API falls back to the store's configured domain (`store.Domain`) or, when `store.Domain` is empty, to the platform base URL (`SiteBaseURL`).

***

## 💳 Card installments

To charge a card in **installments**, inform the number of installments in `metadata.gateway.card.installmentCount`:

```json theme={null}
{
  "metadata": {
    "gateway": {
      "card": {
        "installmentCount": 6
      }
    }
  }
}
```

* **The chosen number is the one that applies** — it must be between `1` and the `maxInstallments` configured in the store gateway (maximum **12**). If it exceeds the limit, the API rejects it with `400 MAX_INSTALLMENTS_EXCEEDED`; if it is invalid (\< 1 or non-integer), `400 INVALID_INSTALLMENT_COUNT`.
* When the merchant configured **installment fee tiers** (`installmentFees`) in the gateway, the fee of the tier containing the `installmentCount` replaces the flat fee of `fees.card` — **applied only once over the total**, which is then equally divided among the installments. Ex.: tiers 1x `0% + R$ 0`, 2–6x `3,49% + R$ 0,49`, 7–12x `3,99% + R$ 0,49`.
* **Application in the gateway**: the supported card gateways (Asaas and Mercado Pago) receive the chosen number of installments and divide the total (fee already embedded) equally in N× across all flows — hosted invoice or tokenized card. On Mercado Pago the checkout is limited to the chosen number (`max_installments`).
* Without the field, the card is charged **upfront (1x)** with the flat fee of `fees.card` (on Mercado Pago, up to the merchant's `maxInstallments`).
* The `installmentCount` is recorded on the payment in `metadata.gateway.card.installmentCount` (alongside `gateway.FeePercentage` / `gateway.FeeAmount`), allowing tracking of how many installments the sale was split into.
* Installment errors return **only the code** (no `message`), following the route standard:

| Status | Code | When |
| - | - | - |
| `400` | `INVALID_INSTALLMENT_COUNT` | invalid `installmentCount` (\< 1 or non-integer) |
| `400` | `MAX_INSTALLMENTS_EXCEEDED` | `installmentCount` above the store's `maxInstallments` |

***

## 💳 Transparent card (tokenized)

To charge the card **without redirecting** the buyer, the frontend tokenizes the data in the browser (public SDK of the gateway, with the public key) and sends only the token in `metadata.card` — the card data never passes through the API:

```json theme={null}
{
  "metadata": {
    "card": {
      "creditCardToken": "TOKEN_GERADO_NO_FRONTEND"
    },
    "gateway": { "card": { "installmentCount": 6 } }
  }
}
```

* The token is also accepted in `metadata.gateway.card.creditCardToken`. The installments remain in `metadata.gateway.card.installmentCount` (validated against the store's `maxInstallments`).
* **Without a token, nothing changes**: the flow falls back to the hosted checkout (redirect) as before.
* **Mercado Pago**: with a token, the API charges directly (`POST /v1/payments`) and responds **without** `init_point` — comes `paymentId`, `status` and `statusDetail`; the final status is tracked by the verification queue (queries the payment in the gateway). Optional: `paymentMethodId` and `issuerId` (the MP SDK reports both).
* **Asaas**: with a token (`creditCardToken`, or `creditCard` + `creditCardHolderInfo`), charges directly; without a token, generates the hosted invoice (`invoiceUrl` / `init_point`).
* **EFI Bank**: card payments require `metadata.gateway.card.payment_token` from the EFI frontend SDK and `metadata.gateway.card.phone_number`.
* Gateway error (e.g.: invalid token) returns `502 GATEWAY_ERROR` with the `error` field containing the provider's response body — no charge is created.

***

## ✅ Example request

```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 }
    ]
  }'
```

For Mercado Pago boleto, set `gateway` to `MERCADOPAGO_ORDER_BOLETO`; for Mercado Pago balance, use `MERCADOPAGO_ORDER_SALDO`. Both use the same body as the PIX example; only change `gateway`.

### 💳 Example with 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 }
    ]
  }'
```

For Asaas boleto, use the same request and set `gateway` to `ASAAS_ORDER_BOLETO`. For hosted card checkout, use `ASAAS_ORDER_CARD`; for a direct card charge, also send a card token and holder details as described in the **Transparent card (tokenized)** section.

### 💳 Example with 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 }
    ]
  }'
```

For boleto, set `gateway` to `EFI_BANK_ORDER_BOLETO`. EFI card requires frontend tokenization and the buyer's phone number:

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

### 💳 Example with 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://store.example.com/payment/success",
      "cancelUrl": "https://store.example.com/payment/cancelled"
    },
    "items": [
      { "productId": "PRODUCT_ID", "quantity": 1 }
    ]
  }'
```

For Stripe card or boleto, change `gateway` to `STRIPE_ORDER_CARD` or `STRIPE_ORDER_BOLETO`. If `successUrl` or `cancelUrl` are omitted, the API falls back to the store's domain (`store.Domain`) or `SiteBaseURL` when the store has no domain configured.

### 💳 Example with installment card (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 }
    ]
  }'
```

***

## 📦 Responses

### 201 — Payment 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 — Payment via gateway (Card / 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 — Payment 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"
      }
    }
  }
}
```

> For **Asaas**, track the `status` / `id` via `metadata.gateway` in the payment filter (the verification queue queries the gateway directly). The hosted invoice (`invoiceUrl` / `init_point`) lets the buyer pay by PIX, card or boleto without tokenization.

### 201 — Free payment

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

### 200 — Idempotency replay (`Idempotency-Key` / `idempotencyKey`)

When a request reuses an already processed key in the store (via the `Idempotency-Key` header or the `idempotencyKey` body field), the API does not create a duplicate payment and returns HTTP **`200`** with the original saved response payload:

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

> If the original response has not been persisted yet, the `200` fallback returns `{"status": true, "data": {"payment": {"uuid": "...", "status": "..."}}}`.

***

## ⚠️ Errors

| Status | Code | Description |
| - | - | - |
| `400` | `INVALID_DATA` | Invalid body or missing field |
| `400` | `INVALID_INSTALLMENT_COUNT` | Invalid number of installments (\< 1 or non-integer) |
| `400` | `MAX_INSTALLMENTS_EXCEEDED` | `installmentCount` above the store's `maxInstallments` |
| `400` | `GATEWAY_NOT_ENABLED` | Gateway not enabled in the store |
| `400` | `INVALID_COUPON` | Coupon does not exist or does not apply to the products |
| `400` | `COUPON_EXPIRED` | Expired coupon or no uses left |
| `400` | `COUPON_AFFILIATE_ONLY` | Coupon restricted to specific affiliate codes |
| `400` | `COUPON_PAYMENT_METHOD_INVALID` | Coupon not allowed for the selected gateway/payment method |
| `400` | `COUPON_ALREADY_USED` | Single-use coupon already used by this customer (email or CPF) |
| `400` | `COUPON_MIN_ORDER_AMOUNT` | Order subtotal below the coupon's minimum amount |
| `400` | `COUPON_MIN_ITEMS_QUANTITY` | Total item quantity below the coupon's minimum |
| `400` | `OUT_OF_STOCK` | Insufficient stock (includes `productId` field) |
| `400` | `PRODUCT_DISABLED` | Product disabled for purchase (includes `productId` field) |
| `401` | `UNAUTHENTICATED` | Failed to identify store owner during plan validation |
| `403` | `NO_ACTIVE_SUBSCRIPTION` | Store owner subscription inactive or expired |
| `404` | `STORE_NOT_FOUND` | Store not found |
| `404` | `PRODUCT_NOT_FOUND` | Product not found (includes `productId` field) |
| `429` | `RATE_LIMIT_EXCEEDED` | Plan per-minute rate limit exceeded |
| `500` | `GATEWAY_ERROR` | Internal error while processing gateway response (includes `error` field) |
| `500` | `INTERNAL_SERVER_ERROR` | Internal error |
| `502` | `GATEWAY_ERROR` | Error returned by payment provider (includes `error` field with provider body) |
| `503` | `SERVICE_UNAVAILABLE` | Service temporarily unavailable |

> For `400 OUT_OF_STOCK`, `400 PRODUCT_DISABLED`, and `404 PRODUCT_NOT_FOUND`, the response includes the `productId` field identifying the 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.