canonical: https://jentic.com/apis/clip.mx/clip

# Clip Mx Clip Payments API

Jentic publishes the only available OpenAPI specification for Clip Payments API, keeping it validated and agent-ready. Clip is a Mexican payments processor and the v2 API exposes the surface a merchant needs to accept card payments online and in person. The 15 endpoints cover hosted payment links, transparent checkout with card tokenisation, transactions and refunds, settlements and deposits, and PinPad device integration for in-store card-present payments. Authentication uses HTTP Basic for server-side calls.

## For AI agents

Process card payments in Mexico with Clip - create payment links, tokenise cards for transparent checkout, manage transactions, refunds, deposits, and PinPad device payments.

## Scope

Does not handle bank transfers, OXXO cash payments, or non-Mexican currencies - use for Mexican peso card processing through Clip's online and PinPad rails only.

## Capabilities

- Create hosted payment links and retrieve them by ID via /payment-links and /payment-links/{id}
- Tokenise cards for transparent checkout via POST /tokens
- Create and inspect card transactions via POST /charges and /transactions
- Issue and look up refunds via POST /refunds and /refunds/{refundId}
- Retrieve settlement and deposit records for reconciliation via /settlements and /deposits
- Initiate a PinPad payment on a registered device and check device status via /f2f/pinpad/v1/payment and /f2f/pinpad/v1/devices/status
- Look up an in-progress PinPad payment by serial number via /f2f/pinpad/v1/payment/serial-number/{serialNumber}

## Use cases

### Online Checkout with Tokenised Cards

Accept online card payments in Mexico without storing PAN data by tokenising the card via /tokens and then charging the token via /charges. The transparent checkout flow keeps the merchant out of PCI scope while still supporting custom checkout UX.

Example prompt: Tokenise a card via POST /tokens, then charge the token via POST /charges with the amount in MXN and the order reference.

### Hosted Payment Links for Invoicing

Generate Clip payment links and send them to customers when an in-app checkout is not available - useful for invoices, deposits, and one-off charges. Once paid, the merchant retrieves the link state via /payment-links/{id} to confirm settlement.

Example prompt: Create a payment link via POST /payment-links for 1500 MXN and send the returned URL to the customer, then poll /payment-links/{id} until the link is paid.

### In-Person PinPad Card-Present Payments

Drive Clip PinPad terminals from a back-office or kiosk app by initiating a payment, polling the device, and confirming completion. The /f2f/pinpad/v1/payment, /f2f/pinpad/v1/devices/status, and /f2f/pinpad/v1/payment/serial-number/{serialNumber} endpoints together support card-present sales without closing on-screen flows.

Example prompt: Trigger a PinPad payment via POST /f2f/pinpad/v1/payment for the device serial, then poll /f2f/pinpad/v1/payment/{paymentId} until the result is final.

### Settlement and Refund Reconciliation

Reconcile Clip activity against bank deposits and accounting entries by pulling transactions, refunds, settlements, and deposit records on a daily basis. The /transactions, /refunds, /settlements, and /deposits endpoints provide the underlying records for finance teams.

Example prompt: Pull /settlements and /deposits for the previous day, join the records to /transactions, and emit a reconciliation report against the merchant bank statement.

### AI Agent Payments for Mexican Merchants via Jentic

An AI agent that handles billing for a Mexican merchant can create payment links, charge tokenised cards, issue refunds, or trigger PinPad terminals by searching Jentic for the matching Clip operation. Jentic securely stores the Basic auth credentials so the agent never holds them directly.

Example prompt: Use the Jentic search query 'create a payment link' to find POST /payment-links and execute with the amount and order reference.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /payment-links | Create a hosted payment link |
| POST | /tokens | Tokenise a card for transparent checkout |
| POST | /charges | Charge a tokenised card |
| POST | /refunds | Issue a refund |
| GET | /transactions | List transactions |
| GET | /settlements | List settlement records |
| POST | /f2f/pinpad/v1/payment | Trigger a card-present payment on a PinPad device |
| GET | /f2f/pinpad/v1/devices/status | Check PinPad device status |

## Key resources

- **PaymentLinks** — Create and inspect hosted payment links
- **Checkout** — Tokenise cards and charge them via transparent checkout
- **Transactions** — Inspect and manage card transactions
- **Refunds** — Issue and look up refunds
- **Deposits** — Retrieve deposit records for reconciliation
- **Settlements** — Retrieve settlement records
- **PinPad** — Initiate and inspect card-present payments on Clip PinPad terminals

## Why Jentic

- **Setup:** Wiring Clip by hand means assembling its HTTP Basic header, mapping its online payment and PinPad face-to-face endpoints, and handling retries yourself against api.clip.mx. Through Jentic you install once, import the Clip Payments API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Clip's payment targets like a charge or a refund carry their identifiers in the request body rather than the URL path, so scope the agent to the operations it needs, such as creating a payment link or reading transactions. You choose which operations are in that set, so issuing refunds or charges are not included unless you add them.
- **Credential handling:** Your Clip HTTP Basic credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a payment link' or 'issue a refund', and Jentic returns the matching Clip operation with its input schema, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe** — Global card processing with broad currency and method coverage
- **Conekta** — Mexico-focused payments processor with cards and OXXO support
- **Stripe** — Global processing for cross-border revenue alongside local Mexican acquirer

## FAQ

### Why is there no official OpenAPI spec for Clip Payments API?

Clip does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Clip Payments 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 Clip Payments API use?

The API uses HTTP Basic authentication for server-side calls. Through Jentic the Basic credentials are stored encrypted in the vault and the agent only ever holds a scoped execution context.

### Can I tokenise a card and charge it with the Clip API?

Yes. POST a card payload to /tokens to receive a token, then POST that token to /charges with the amount and currency to authorise the charge. This keeps the merchant out of PCI scope on the card data path.

### How do PinPad payments work?

Trigger a payment on a registered device via POST /f2f/pinpad/v1/payment with the device serial, then poll /f2f/pinpad/v1/payment/{paymentId} until the cardholder taps or inserts and the payment finalises. Device readiness can be checked via /f2f/pinpad/v1/devices/status.

### How do I issue a refund through Jentic?

Search Jentic for 'issue a refund', load the schema for POST /refunds, and execute with the original transaction ID and the refund amount. The Python SDK uses await client.search, await client.load, await client.execute.

### Does Clip support multiple currencies?

Clip is focused on Mexican peso (MXN) processing for Mexican merchants. The /charges and /payment-links endpoints accept MXN amounts; cross-border or multi-currency flows are not in scope of this API.

### Can I limit what my agent is allowed to do with the Clip Payments API?

Yes. Because you run Jentic One yourself, your own rules decide which Clip operations and credentials the agent may use, so you can grant it just what it needs, such as creating a payment link via POST /payment-links or reading records via GET /transactions. Clip carries payment identifiers like a charge or refund in the request body rather than the URL path, so money-moving operations such as POST /charges and POST /refunds stay out of the agent's allowed set unless you add them. This keeps the agent scoped to the exact calls you approve.