canonical: https://jentic.com/apis/helcim.com/helcim

# Helcim The Helcim API

Jentic publishes the only available OpenAPI specification for The Helcim API, keeping it validated and agent-ready. Helcim is a Canadian payment processor offering interchange-plus pricing for merchants. The v2 API exposes purchase, preauth, capture, verify, refund, reverse, and withdraw transaction flows, plus customer profile management with stored cards, card-batch settlement, and connection testing. Authentication uses a per-merchant API token (ApiAccessAuth header).

## For AI agents

Process card payments, manage customers and stored cards, and settle batches with Helcim across 28 endpoints.

## Scope

Does not handle accounting, payroll, tax filing, or invoicing - use for card payment processing, customer card vaulting, and batch settlement only.

## Capabilities

- Process a purchase, preauth, capture, verify, refund, reverse, or withdraw transaction via the /payment/* endpoints
- Retrieve a card transaction by id via GET `/card-transactions/{cardTransactionId}`
- Settle an open card batch via POST `/card-batches/{cardBatchId}/settle`
- Manage customer profiles and update billing details via GET/PUT `/customers/{customerId}`
- List, retrieve, and remove a customer's stored cards via `/customers/{customerId}/cards` endpoints
- Test connectivity and credential validity via GET /connection-test

## Use cases

### E-Commerce Checkout

An online store accepts card payments by calling POST `/payment/purchase` with the order amount and tokenised card. Helcim handles authorisation, capture, and settlement; the store receives the transaction id to attach to the order. Refunds and reversals are issued through the matching `/payment/refund` or `/payment/reverse` endpoint when needed.

Example prompt: Call POST `/payment/purchase` with amount, currency, and a card token, then store the returned transactionId on the order

### Preauth and Delayed Capture

A hotel preauthorises the card at check-in via POST `/payment/preauth` and captures the final amount at check-out via POST `/payment/capture` once incidentals are settled. Helcim manages the auth-hold lifecycle so the merchant only captures what was actually used.

Example prompt: Call POST `/payment/preauth` on check-in, then POST `/payment/capture` with the preauth id and final amount on check-out

### Recurring Customer Card Vault

A subscription business stores customers and their cards in Helcim and charges them on each renewal. The /customers and `/customers/{customerId}/cards` endpoints supply the vaulted card; POST `/payment/purchase` against that customer charges the stored card without re-collecting card details.

Example prompt: List a customer's cards via GET `/customers/{customerId}/cards` and call POST `/payment/purchase` using the chosen card id to renew their subscription

### AI Agent Payment Operations Assistant

An ops agent answers 'refund last Tuesday's $120 charge to John Smith' by searching Jentic for the right Helcim operation, loading `/payment/refund`, and executing it with the resolved transaction id. The agent never sees the API token; Jentic injects it server-side.

Example prompt: Search Jentic for 'refund a helcim transaction', load POST `/payment/refund`, and execute it with the original transaction id and amount

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/payment/purchase` | Process a purchase transaction |
| POST | `/payment/preauth` | Pre-authorise a card |
| POST | `/payment/capture` | Capture a previously authorised amount |
| POST | `/payment/refund` | Refund a transaction |
| POST | `/payment/reverse` | Reverse a transaction |
| POST | `/card-batches/{cardBatchId}/settle` | Settle an open card batch |
| GET | `/customers/{customerId}` | Retrieve a customer profile |
| GET | `/customers/{customerId}/cards` | List a customer's stored cards |

## Key resources

- **Payments** — Process purchase, preauth, capture, verify, refund, reverse, and withdraw transactions
- **Card Batches** — Inspect and settle the merchant's daily card batches
- **Card Transactions** — Retrieve a single card transaction by id
- **Customers** — Manage customer profiles and contact information
- **Customer Cards** — List, retrieve, and remove a customer's stored cards
- **Connection Test** — Verify API connectivity and credentials

## Why Jentic

- **Setup:** Wiring Helcim by hand means sending your merchant api-token header on every payment call and tracking settlement state to pick between reversals and refunds. Through Jentic you install once, import the Helcim API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Helcim puts resource ids in the URL path (`/customers/{customerId}`, `/card-batches/{cardBatchId}/settle`), so a rule can pin your agent to one customer: it can read that customer and their stored cards and nothing else. You choose the operations it may call, so ones like a purchase, refund, or reversal are not included unless you add them.
- **Credential handling:** Your Helcim API token is stored once, encrypted, by your own Jentic One instance and injected as the api-token header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a credit card payment' or 'refund a transaction', and Jentic returns the matching Helcim operation with its input schema, including the choice between `/payment/refund` and `/payment/reverse` based on settlement state, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Stripe is the dominant global card processor - broader feature set than Helcim's North American focus
- **Square API** — Square offers payments plus point-of-sale hardware, an alternative for omnichannel merchants
- **PayPal Payments API** — PayPal supports cards plus its wallet, a broader alternative to Helcim's card-focused processing
- **Recurly API** — Recurly handles subscription billing logic that can sit on top of a Helcim payment gateway

## FAQ

### Why is there no official OpenAPI spec for The Helcim API?

Helcim publishes API documentation but the maintained OpenAPI source available is the Konfig examples version. Jentic generates and maintains a clean spec so AI agents and developers can call Helcim 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 Helcim API use?

Helcim uses an API token sent in the api-token header (ApiAccessAuth scheme). Through Jentic, the token is stored encrypted in the vault and the agent receives scoped access at execution time.

### Can I issue a refund through the Helcim API?

Yes. POST `/payment/refund` refunds a previously settled transaction; for a transaction that hasn't yet settled, use POST `/payment/reverse` instead.

### What are the rate limits for The Helcim API?

The OpenAPI spec does not publish hard rate limits; Helcim applies fair-use limits per merchant account. For batch settlement and reporting jobs, GET /connection-test first to confirm the token is healthy before bulk traffic.

### How do I process a purchase through Jentic?

Run pip install jentic, have the agent search for 'process a credit card payment with helcim', load POST `/payment/purchase`, and execute it with amount, currency, and a card token.

### Does Helcim support a customer card vault?

Yes. The /customers and `/customers/{customerId}/cards` endpoints store customer profiles and tokenised cards so subsequent purchases can charge a stored card by id without re-collecting card details.

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

Yes. Because Jentic One is self-hosted, your own rules decide which Helcim operations and credentials the agent may use. Since Helcim puts resource ids in the URL path, such as `/customers/{customerId}` and `/card-batches/{cardBatchId}/settle`, you can pin the agent to a single customer so it only reads that customer and their stored cards. You also pick the exact operations it may call, so payment actions like POST `/payment/purchase`, POST `/payment/refund`, and POST `/payment/reverse` are excluded unless you add them.