canonical: https://jentic.com/apis/cielo.com.br/cielo-com-br

# Cielo E-commerce API

Jentic publishes the only available OpenAPI specification for Cielo E-commerce API, keeping it validated and agent-ready. Cielo is one of the largest payment acquirers in Brazil and its e-commerce API processes credit cards, debit cards, Pix, boleto, e-wallets, QR code payments, and recurring billing through a single REST surface. The API covers transaction creation, capture, void, recurrence management, card tokenisation, and BIN lookup, with separate base URLs for transactional writes and queries. It is the standard payment integration for Brazilian merchants who need to support local payment methods alongside cards.

## For AI agents

Process Brazilian e-commerce payments through Cielo - credit, debit, Pix, boleto, recurring billing, and card tokenisation.

## Scope

Does not handle in-person POS terminals, captioning, or accounting - use for online Brazilian payment processing and recurring billing only.

## Capabilities

- Create credit card, debit card, Pix, and boleto payment transactions via POST `/1/sales`
- Capture pre-authorised payments and void or refund transactions via PUT `/1/sales/{paymentId}` and PUT `/1/sales/{paymentId}/void`
- Manage recurring payment plans including update, deactivate, and reactivate flows under `/1/RecurrentPayment/{recurrentPaymentId}`
- Tokenise cards for repeat use via POST `/1/card` and validate cards without charging via POST `/1/zeroauth`
- Look up card BIN information through `/1/consultabin/{bin}` for issuer and brand routing decisions
- Query payments by Cielo PaymentId or merchant order ID for reconciliation

## Use cases

### Brazilian E-commerce Checkout

Brazilian merchants accept payment at checkout via the local payment mix - credit cards, debit cards, Pix instant transfer, and boleto bancário. POST `/1/sales` accepts a single transaction payload that selects the payment method, and Cielo handles authorisation, settlement, and Pix QR code generation. This avoids needing separate integrations for each payment method.

Example prompt: POST `/1/sales` with a credit card transaction for R$199.90 and return the payment ID and authorisation status

### Subscription Billing in Brazil

SaaS and subscription businesses in Brazil charge customers monthly or annually using Cielo's recurring payment endpoints. POST `/1/sales` creates the initial recurrence and the `/1/RecurrentPayment/{recurrentPaymentId}` endpoints allow update, deactivate, and reactivate flows for cancellations and reactivations. Card tokenisation through `/1/card` stores the payment method for future cycles without holding raw PAN data.

Example prompt: Create a recurring payment via POST `/1/sales` for R$49.90 monthly and store the resulting recurrentPaymentId for cancellation later

### Pre-authorisation and Capture

Travel, hospitality, and marketplace merchants pre-authorise a card at booking and capture later when the service is delivered. POST `/1/sales` with capture=false reserves funds, and PUT `/1/sales/{paymentId}` captures the authorised amount when ready, or PUT `/1/sales/{paymentId}/void` releases the authorisation if the booking is cancelled.

Example prompt: POST `/1/sales` with capture=false for R$1500, then later PUT `/1/sales/{paymentId}` to capture R$1320 once final billing is known

### Card Tokenisation and BIN Routing

Merchants who want to reduce PCI scope tokenise card details once and reference the token for future charges. POST `/1/card` returns a Cielo card token, `/1/zeroauth` validates the card without charging, and `/1/consultabin/{bin}` returns issuer and brand information so the front-end can route the payment to the optimal acquirer or apply card-specific rules.

Example prompt: POST `/1/card` to tokenise a credit card and use the returned token in a follow-up POST `/1/sales` for R$89

### Agent-Driven Payment Reconciliation

An AI agent reconciling daily payments calls Cielo through Jentic to query each merchantOrderId against the orders system and confirm settlement status. The agent searches Jentic for 'query a Cielo payment by order ID', loads the operation, and walks through every order from the day to flag mismatches without an engineer building bespoke ETL.

Example prompt: Search Jentic for 'query a Cielo payment by order ID', load `/1/sales/{merchantOrderId}`, and check status for each order from yesterday

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/1/sales` | Create a payment transaction |
| GET | `/1/sales/{paymentId}` | Query a payment by ID |
| PUT | `/1/sales/{paymentId}` | Capture a pre-authorised payment |
| PUT | `/1/sales/{paymentId}/void` | Void or cancel a payment |
| POST | `/1/card` | Tokenise a card |
| POST | `/1/zeroauth` | Validate a card without charging |
| GET | `/1/consultabin/{bin}` | Look up card BIN information |

## Key resources

- **Sales** — Payment transaction creation, capture, void, and query
- **Recurrent Payments** — Subscription and recurring billing management
- **Card** — Card tokenisation, zero-auth validation, and BIN lookup

## Why Jentic

- **Setup:** Wiring Cielo E-commerce by hand means handling its paired MerchantId and MerchantKey headers and choosing between the transaction and query hosts for each call. Through Jentic you install once, import the Cielo E-commerce API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Cielo puts the payment id in the URL path (`/1/sales/{paymentId}`), so a rule can pin your agent to one sale: it can read and update that payment and nothing else. You choose the operations it may call, so voiding a sale is not included unless you add it.
- **Credential handling:** Your Cielo MerchantId and MerchantKey are stored once, encrypted, by your own Jentic One instance and injected into the headers at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a Brazilian payment with Cielo' or 'check a payment status', and Jentic returns the matching Cielo operation with its payment-method-specific schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe** — Global payments platform with growing Brazilian market support
- **Adyen Checkout** — Enterprise-grade global payment processor with Brazilian market coverage
- **PayPal Orders** — PayPal wallet payment as a complementary checkout option

## FAQ

### Why is there no official OpenAPI spec for Cielo E-commerce API?

Cielo does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Cielo E-commerce API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Cielo E-commerce API use?

Cielo uses two API key headers - MerchantId identifies the merchant and MerchantKey is the secret credential. Both must be present on every request. Through Jentic, both keys are stored encrypted in the vault and the agent never sees the raw values.

### Can I accept Pix payments through the Cielo API?

Yes. POST `/1/sales` supports Pix as a payment method - the response includes the QR code payload and copia-e-cola string the customer uses to complete the transfer. Settlement notification arrives via webhook or via polling `/1/sales/{paymentId}` for status changes.

### How do I set up recurring payments with Cielo?

Create the initial recurrence by passing recurrence parameters to POST `/1/sales.` Cielo returns a recurrentPaymentId you then manage via `/1/RecurrentPayment/{recurrentPaymentId}` for updates, /Deactivate to pause, and /Reactivate to resume - covering the full subscription lifecycle.

### What are the rate limits for the Cielo E-commerce API?

Specific rate limits are not declared in the OpenAPI spec - Cielo applies tenant-level throttling on both the transaction host (api.cieloecommerce.cielo.com.br) and the query host (apiquery.cieloecommerce.cielo.com.br). Honour 429 responses and avoid tight polling loops on payment status.

### How do I create a payment with Cielo through Jentic?

Run pip install jentic, search for 'process a Brazilian payment with Cielo', load the POST `/1/sales` operation, and execute with the order amount, payment method, and customer payload. Jentic injects the MerchantId and MerchantKey headers from the vault.

### Can I limit what my agent is allowed to do with the Cielo E-commerce API?

Yes. Because you run Jentic One yourself, your own rules decide which Cielo operations and credentials the agent may use. Cielo carries the payment id in the URL path (`/1/sales/{paymentId}`), so a rule can pin the agent to a single sale, letting it read and update that payment and nothing else. You pick the operations it may call, so an action like voiding a sale via PUT `/1/sales/{paymentId}/void` is excluded unless you explicitly grant it.