canonical: https://jentic.com/apis/malga.io/malga

# Malga Documentação Malga API

Jentic publishes the only available OpenAPI specification for Documentação Malga API, keeping it validated and agent-ready. Malga is a Brazilian payment-orchestration platform whose API exposes 46 endpoints for charges, sessions, customers, cards, tokens, sellers, merchants, webhooks, and reports. The API authenticates with paired X-Client-Id and X-API-Key headers and supports the full payment lifecycle from token creation through capture, void, and antifraud status changes in the sandbox environment.

## For AI agents

Process card payments, manage charges and sessions, and handle customers and webhooks on the Malga payment orchestration platform. Used by agents that automate Brazilian e-commerce checkout flows and reconcile payment events.

## Scope

Does not handle accounting, tax filing, or invoicing - use for card payment orchestration, charges, sessions, and webhooks only.

## Capabilities

- Tokenise a card and create a stored card object for future charges
- Create a new charge against a token or stored card with capture or pre-auth flag
- Capture a previously pre-authorised charge or void an approved charge
- Open a session that bundles multiple charges and pay it as one unit
- Register a webhook to receive charge, session, and antifraud event callbacks
- Manage merchant and seller records for marketplace split-payment scenarios
- Run reports on sales, refunds, and reconciliation for a date range

## Use cases

### One-Time Card Checkout

Brazilian e-commerce checkouts need a card-tokenise-then-charge flow that handles 3DS, antifraud, and capture in one orchestration. Malga's tokens, cards, and charges endpoints together let an integration tokenise the card on the client, create a stored card, and charge it with capture set to true. The same flow supports pre-auth followed by a separate capture call.

Example prompt: POST `/v1/tokens` with the card data, POST `/v1/cards` with the token, then POST `/v1/charges` referencing the card with capture=true.

### Pre-Auth and Capture Flow

Hospitality and rental businesses pre-authorise a card at booking and capture later when the service is consumed. Malga's charges endpoint supports capture=false to create the pre-auth and POST `/v1/charges/{id}/capture` to settle the funds when the customer checks out. Voiding a pre-auth releases the hold without a settlement.

Example prompt: POST `/v1/charges` with capture=false at booking, then POST `/v1/charges/{id}/capture` at check-out - or POST `/v1/charges/{id}/void` on cancellation.

### Marketplace Split Payments

Marketplaces need to split a single customer payment between multiple sellers and the platform. Malga's sellers, merchants, and charges endpoints support split-payment configuration where each charge declares its split rules and Malga settles the right share to each seller. The same flow underpins service marketplaces and multi-vendor checkout.

Example prompt: Configure sellers via POST `/v1/sellers`, then POST `/v1/charges` with the split rules to settle each seller's share automatically.

### AI Agent Payment Operator

Finance and ops teams can delegate routine payment lookups, retries, and refunds to an agent. Through Jentic the agent searches by intent, loads the schema, and executes the right Malga operation while X-Client-Id and X-API-Key stay in the encrypted vault. The same loop powers checkout assistants and finance copilots.

Example prompt: Use Jentic to search 'create a charge on malga', execute POST `/v1/charges` with the resolved customer and amount, and report the charge ID and status.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/tokens` | Create a token from raw card data |
| POST | `/v1/cards` | Create a stored card from a token |
| POST | `/v1/charges` | Create a charge |
| GET | `/v1/charges` | List charges |
| POST | `/v1/charges/{id}/capture` | Capture a pre-authorised charge |
| POST | `/v1/charges/{id}/void` | Void an approved charge |
| POST | `/v1/sessions` | Create a session that bundles charges |

## Key resources

- **Charges** — Create, list, capture, void, and inspect charges including antifraud status.
- **Sessions** — Bundle multiple charges into a session and pay or update the session as a unit.
- **Customers** — Manage customer records linked to stored cards and charges.
- **Cards and Tokens** — Tokenise card data and create stored cards for repeated charges.
- **Sellers and Merchants** — Manage marketplace seller and merchant records used in split-payment flows.
- **Webhooks** — Register webhooks for charge, session, and antifraud event callbacks.
- **Reports** — Generate sales, refund, and reconciliation reports for a chosen date range.

## Why Jentic

- **Setup:** Wiring the Malga API by hand means sending both its client-id and API-key request headers, targeting the api.malga.io host, and driving its token, card, charge, and session endpoints yourself. Through Jentic you install once, import Malga from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Malga puts the charge id in the URL path (`/charges/{id}/capture`, `/charges/{id}/void`), so a rule can pin your agent to one charge. You choose the operations it may call, so capturing or voiding a charge is not included unless you add it.
- **Credential handling:** Your Malga client id and API key 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 charge' or 'capture a payment', and Jentic returns the matching Malga operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Stripe is a global payment processor with overlapping charge, capture, and void semantics.
- **Adyen Account Service** — Adyen is a global payment platform that competes with Malga in larger Brazilian merchants.
- **PayPal Invoicing API** — PayPal handles invoiced and wallet payments that complement Malga's card orchestration.

## FAQ

### Why is there no official OpenAPI spec for Documentação Malga API?

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

Malga requires both X-Client-Id and X-API-Key headers on every request. Through Jentic both values are stored encrypted in the vault and attached at execute time, so the secrets never reach the agent context.

### Can I tokenise a card before charging it?

Yes. POST `/v1/tokens` accepts the raw card data and returns a token; POST `/v1/cards` turns that token into a stored card. The charges endpoint then references the stored card rather than the raw card data.

### How do I capture a pre-authorised charge?

Create the charge with capture set to false, then call POST `/v1/charges/{id}/capture` when you are ready to settle. POST `/v1/charges/{id}/void` releases a pre-auth instead of capturing it.

### What are the rate limits for the Malga API?

Rate limits are not declared in the OpenAPI spec - they depend on your Malga contract and environment (sandbox versus production). Confirm with Malga support before driving high-volume traffic.

### How do I create a charge through Jentic?

Run pip install jentic, search 'create a charge on malga', load the schema for POST `/v1/charges`, and execute with the card or token reference and amount. Jentic injects X-Client-Id and X-API-Key from the vault.

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

Yes. Because you run Jentic One yourself, your own rules decide which Malga operations and credentials the agent may use, so you can allow it to create or list charges while withholding capture and void. Malga puts the charge id in the URL path for POST `/v1/charges/{id}/capture` and POST `/v1/charges/{id}/void`, so a rule can also pin the agent to a single charge. The agent can only call the operations you have granted, and your X-Client-Id and X-API-Key are attached at execution time rather than exposed to it.