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

# Beanstream Payments

Jentic publishes the only available OpenAPI specification for Beanstream Payments, keeping it validated and agent-ready. Beanstream (now Bambora North America) is a Canadian payment processor that accepts credit card and tokenized payments, manages stored card profiles for repeat billing, and runs settlement and refund operations. The API exposes 15 endpoints spanning Payments, Profiles, Tokenization, and Reporting, with HTTP Basic authentication using merchant ID and passcode credentials.

## For AI agents

Process credit card payments, manage stored payment profiles, tokenize cards, and run transaction reports through Beanstream's 15-endpoint payments API.

## Scope

Does not handle accounting, tax filing, payouts to bank accounts, or in-person POS terminals - use for online card payments, tokenization, stored profiles, and refunds only.

## Capabilities

- Process card and token-based payments with pre-auth, capture, void, and return flows
- Tokenize raw card numbers via the hosted tokenization endpoint to avoid handling PAN data
- Store and update reusable payment profiles for one-click and recurring charges
- Attach, update, and delete cards on existing customer profiles
- Complete a previously authorised transaction or void an un-captured authorisation
- Issue full or partial returns against a settled transaction
- Pull merchant transaction reports for reconciliation and exception handling

## Use cases

### Card-not-present checkout for Canadian merchants

Accept card-not-present payments through the Beanstream gateway with pre-auth and capture or single-message purchase flows. Merchants tokenize the card client-side via `/scripts/tokenization/tokens` to keep PAN out of their server, then call POST /payments with the token and amount. Beanstream returns an approved or declined response with the transaction ID used for later capture, void, or return calls.

Example prompt: Tokenize a card number 4030000010001234 with expiry 12/27, then create a $59.99 CAD purchase against the resulting token and confirm the response code is approved

### Stored profile billing for subscriptions

Set up customer profiles with one or more saved cards and charge them on demand for subscription renewals or repeat purchases. POST /profiles creates the profile and returns a customer code; subsequent payments reference that code instead of card data, keeping the merchant out of PCI scope on charge attempts. Cards can be added, updated, or removed via `/profiles/{profileId}/cards.`

Example prompt: Create a payment profile for customer order_id 9921 with the tokenized card, then charge the profile $19.00 CAD for a monthly subscription renewal

### Refunds and dispute response

Operations and support teams issue full or partial refunds against settled transactions and void unsettled authorisations through the Payments resource. Refunds use POST `/payments/{transId}/returns` and voids use POST `/payments/{transId}/void`; reporting via POST /reports lets the team match returns against original transactions and respond to chargeback enquiries with auditable settlement data.

Example prompt: Issue a partial return of $25.00 against transaction 10000123 with an order memo customer requested partial refund

### AI agent integration for payment operations

Finance and support agents use AI assistants through Jentic to look up payments, issue refunds, and run reconciliation reports without operating the Beanstream merchant console. The agent searches Jentic for the operation, loads the schema, and executes with the merchant ID and passcode held in your Jentic One instance, so the credentials never appear in the agent transcript.

Example prompt: Through Jentic, find Beanstream's return operation and refund $14.50 against transaction ID 10009987 with reason note duplicate charge

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/payments` | Create a card or token payment |
| GET | `/payments/{transId}` | Look up a transaction by ID |
| POST | `/payments/{transId}/returns` | Issue a return against a settled transaction |
| POST | `/payments/{transId}/void` | Void an unsettled authorisation |
| POST | `/payments/{transId}/completions` | Capture a previously authorised payment |
| POST | `/profiles` | Create a stored payment profile |
| POST | `/profiles/{profileId}/cards` | Add a card to an existing profile |
| POST | `/scripts/tokenization/tokens` | Tokenize a card number |

## Key resources

- **Payments** — Create, complete, void, and return card and token-based transactions
- **Profiles** — Store reusable customer payment profiles and managed card records
- **Tokenization** — Convert a raw card number into a single-use token for safe server-side use
- **Reporting** — Pull merchant transaction reports for reconciliation

## Why Jentic

- **Setup:** Wiring Beanstream Payments by hand means building the HTTP Basic header from your merchant id and the Payments, Profiles, and Reporting passcodes, and threading transaction ids through the void, return, and completion calls yourself. Through Jentic you install once, import Beanstream Payments from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Beanstream puts the transaction id in the URL path (`/payments/{transId}/returns` and `/payments/{transId}/void`), so a rule can pin those follow-up operations to one transaction. You choose the operations the agent may call, so destructive ones like refunds and voids are not included unless you add them.
- **Credential handling:** Your Beanstream merchant id and passcodes are stored once, encrypted, by your own Jentic One instance and used to build the Basic Authorization header at execution time. They never enter 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 Beanstream operation with its input schema so the agent calls POST /payments or POST `/payments/{transId}/returns` without browsing the reference docs.

## Related APIs

- **Stripe** — Global payments processor with broader currency, payment method, and developer tooling coverage than Beanstream's Canadian focus.
- **Square** — Payments and POS platform; alternative for merchants who need both online card processing and in-person terminals.
- **PayPal Invoicing** — Invoicing and PayPal wallet payments commonly used alongside card processors for buyer-funded checkouts.

## FAQ

### Why is there no official OpenAPI spec for Beanstream Payments?

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

Beanstream Payments uses HTTP Basic authentication with the merchant ID as the username and the API passcode (Payments, Profiles, or Reporting passcode depending on the resource) as the password. Jentic's vault stores these credentials and injects the Authorization header at execution time, so the passcode never enters the agent transcript.

### Can I tokenize a card with the Beanstream Payments API to stay out of PCI scope?

Yes. Call POST `/scripts/tokenization/tokens` with the card number, expiry, and CVD to receive a single-use token, then pass that token to POST /payments instead of the raw PAN. Production integrations typically tokenize from the customer's browser so the server never touches the card number.

### How do I refund a Beanstream transaction through Jentic?

Search Jentic for refund a Beanstream payment to find POST `/payments/{transId}/returns.` Load the schema and execute with the original transaction ID, the amount to return, and an order_number. Jentic injects the Returns passcode held in the vault.

### Does Beanstream Payments support stored profiles for recurring billing?

Yes. POST /profiles creates a customer profile that can hold multiple cards. To charge a profile, POST /payments with payment_method set to payment_profile and the customer_code returned by the profile create call. Cards on a profile are managed via `/profiles/{profileId}/cards.`

### What are the rate limits for the Beanstream Payments API?

Beanstream does not publish a public rate limit in the spec; throughput is governed by the merchant account configuration. If you receive HTTP 429 or transaction throttling responses, back off and retry, and contact Bambora support to confirm headroom for high-volume integrations.

### Is Beanstream Payments only for Canadian merchants?

The Beanstream brand serves Canadian merchants under the Bambora North America umbrella. The base URL https://www.beanstream.com/api/v1 routes to the Canadian processing platform; US and other regional Bambora products use different endpoints not covered by this spec.

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

Yes. Because Jentic One is self-hosted, your own rules decide which Beanstream operations the agent may call, so you can allow POST /payments and GET `/payments/{transId}` for charging and lookups while withholding destructive calls like POST `/payments/{transId}/returns` and POST `/payments/{transId}/void` unless you add them. Beanstream carries the transaction id in the URL path for those follow-up operations, so a rule can pin a refund or void to one specific transaction. Your merchant id and passcodes stay under your control and are used only for the operations you permit.