Beanstream Payments
Agent-ready OpenAPI document · curated by JenticPaymentsPayment Processingbasic15 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Process credit card payments, manage stored payment profiles, tokenize cards, and run transaction reports through Beanstream's 15-endpoint payments API.
Use for: Process a credit card payment for an order, Tokenize a card number so I can charge it later, Create a payment profile for a returning customer, Add a new card to an existing customer profile
Not supported: 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.
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.
Install Jentic One Beta
Connect the Beanstream Payments to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Beanstream Payments, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fbeanstream.com%2Fbeanstream" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fbeanstream.com%2Fbeanstream" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Beanstream Payments API.
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
Patterns agents use Beanstream Payments API for, with concrete tasks.
★ 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.
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.
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.
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.
Through Jentic, find Beanstream's return operation and refund $14.50 against transaction ID 10009987 with reason note duplicate charge
Key Endpoints
15 endpoints — jentic publishes the only available openapi specification for beanstream payments, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe
Global payments processor with broader currency, payment method, and developer tooling coverage than Beanstream's Canadian focus.
Choose Stripe when the agent needs international payment methods, in-depth subscription billing primitives, or webhook-driven flows beyond Beanstream's resource set.
FAQs
Specific to using Beanstream Payments API through Jentic.
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.
GET STARTED