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

# MONEI API v1

MONEI is a Spanish payment gateway that lets merchants accept cards, Apple Pay, Google Pay, Bizum, PayPal, and other regional methods through a single integration. The API exposes 29 endpoints covering payment lifecycle (create, confirm, capture, refund, recurring), subscriptions, Apple Pay certificate and domain management, Bizum phone validation, and POS authentication tokens. Multi-account support via the MONEI-Account-ID header lets platforms route transactions on behalf of connected merchants. Rate limiting returns HTTP 429 and all requests must be HTTPS with a User-Agent header.

## For AI agents

Charge cards, accept Bizum and Apple Pay, manage subscriptions, and issue refunds for merchants on the MONEI gateway. Supports platform-style multi-account routing.

## Scope

Does not handle payouts to bank accounts, KYC onboarding, or accounting reconciliation - use for accepting card, Bizum, and wallet payments on the MONEI gateway only.

## Capabilities

- Create one-time card payments and capture or void authorisations on /payments
- Process Bizum mobile payments after validating a phone number on `/bizum/validate-phone`
- Manage Apple Pay merchant certificates and verified domains for in-browser checkout
- Run recurring billing through the /subscriptions resource with plan, pause, resume and cancel actions
- Issue full or partial refunds against a captured payment by referencing the payment id
- Mint short-lived POS authentication tokens so terminals can transact without long-term keys

## Use cases

### Online Card Checkout for Spanish Merchants

Accept cards and local wallets on a Spanish or European storefront by creating a payment on /payments, redirecting the shopper to MONEI's hosted payment page, and confirming the result via webhook. The 29-endpoint API covers authorisation, capture, void, and refund without the merchant touching card data, satisfying PSD2 SCA requirements through the gateway.

Example prompt: Create a MONEI payment for 49.99 EUR with order id ORD-1042 and return the payment URL the customer should be redirected to.

### Bizum Mobile Payments

Bizum is the dominant Spanish peer-to-business mobile payment scheme. With MONEI an agent can validate a customer's phone number on `/bizum/validate-phone`, create a payment with Bizum as the chosen method, and read the final status. This unlocks an additional 25 million Spanish users without negotiating a separate Bizum acquirer.

Example prompt: Validate the Bizum phone number +34600123456 and create a 12.50 EUR Bizum payment if the number is registered.

### Recurring Billing for SaaS

MONEI subscriptions let merchants store a card on file and charge on a schedule via /subscriptions. The API supports pause, resume, plan changes, and cancellation, with each cycle producing a child payment that can be reconciled against accounting. Useful for European SaaS that need EUR-native billing without USD conversion.

Example prompt: Create a monthly 19.99 EUR subscription for customer cus_77 starting on the next billing date and confirm the first charge succeeded.

### Apple Pay on the Web

Apple Pay on the web requires both a merchant identity certificate and a list of verified domains. MONEI exposes `/apple-pay/certificates` and `/apple-pay/domains` so an agent can provision and rotate certificates and register checkout domains programmatically. This removes a manual step from launching new branded storefronts on the gateway.

Example prompt: Register checkout.example.com as an Apple Pay domain on the active MONEI certificate and verify activation.

### AI Agent Payment Operations

An autonomous commerce agent uses Jentic to discover MONEI's payment, refund and subscription endpoints, loads their JSON Schemas, and executes calls without touching raw API keys. The Authorization header and MONEI-Account-ID are injected from your Jentic One instance, so the same agent can operate across many merchant accounts on a platform without storing per-merchant secrets in its own context.

Example prompt: Search Jentic for 'process a card payment', load the MONEI create-payment schema, and execute a 25 EUR charge for account acc_123.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/payments` | Create a payment |
| GET | `/payments/{id}` | Retrieve a payment |
| POST | `/payments/{id}/refund` | Refund a payment |
| POST | `/subscriptions` | Create a subscription |
| POST | `/bizum/validate-phone` | Validate a Bizum phone number |
| POST | `/apple-pay/domains` | Register an Apple Pay domain |
| GET | `/payment-methods` | List enabled payment methods |

## Key resources

- **Payments** — Create, retrieve, capture, refund, and confirm card and wallet payments
- **Subscriptions** — Recurring billing with pause, resume, plan change, and cancellation
- **Payment Methods** — List enabled methods (cards, Bizum, Apple Pay, PayPal, Google Pay) per account
- **Apple Pay Certificate** — Provision, activate, and rotate Apple Pay merchant certificates
- **Apple Pay Domain** — Register and verify domains for Apple Pay on the web
- **Bizum** — Validate Spanish mobile numbers before initiating Bizum payments
- **POS Auth Token** — Short-lived tokens for in-person terminal transactions

## Why Jentic

- **Setup:** Wiring the MONEI API by hand means setting both the Authorization key and the per-merchant MONEI-Account-ID header, handling Bizum and wallet flows, and coding the payment and refund calls yourself. Through Jentic you install once, import the MONEI API from the API Directory, store the key and account id once, and your agent calls it.
- **Permission scoping:** MONEI puts the payment id in the URL path (`/payments/{id}`, `/payments/{id}/refund`), so a rule can pin your agent to one payment and the operations on it. You choose the operations it may call, so a destructive one like refunding a payment is not included unless you add it.
- **Credential handling:** Your MONEI key and MONEI-Account-ID are stored once, encrypted, by your own Jentic One instance and injected at execution time, even on multi-tenant platforms. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a card payment in Spain' or 'refund a payment', and Jentic returns the matching MONEI operation with its input schema so the agent calls the right endpoint without browsing the developer docs.

## Related APIs

- **Stripe API** — Global payment gateway with broader currency and method coverage but no native Bizum
- **Adyen Checkout API** — Enterprise European acquirer with single-platform card, wallet, and local method support
- **Braintree API** — PayPal-owned gateway with strong wallet support but limited Spanish local methods
- **PayPal Payments API** — Add PayPal wallet alongside MONEI's card and Bizum acceptance

## FAQ

### What authentication does the MONEI API use?

MONEI uses an API key passed in the Authorization header, with an optional MONEI-Account-ID header for platforms acting on behalf of a connected merchant. Through Jentic the key lives in the credential vault and is injected at execution time, so the agent never sees the raw secret.

### Can I accept Bizum with the MONEI API?

Yes. Call POST `/bizum/validate-phone` with the Spanish mobile number to confirm it is registered for Bizum, then create a payment on POST /payments with Bizum selected as the method. MONEI returns a payment URL or a status the customer's bank app uses to confirm.

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

MONEI returns HTTP 429 Too Many Requests when limits are exceeded. The exact per-second quota is not published in the spec; back off on 429 and retry with exponential delay. All requests must be HTTPS and include a valid User-Agent header or they are rejected with 401.

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

Search Jentic for 'refund a MONEI payment', load the schema for POST `/payments/{id}/refund`, and execute it with the payment id and refund amount. Jentic handles the Authorization header so you only supply the business inputs.

### Does MONEI support recurring subscriptions?

Yes, the /subscriptions resource provides create, retrieve, pause, resume, update plan, and cancel operations. Each billing cycle generates a child payment that can be reconciled or refunded individually like any other MONEI payment.

### How do I register an Apple Pay domain on MONEI?

Provision a merchant certificate through POST `/apple-pay/certificates`, activate it on POST `/apple-pay/certificates/{id}/activate`, then register each checkout domain on POST `/apple-pay/domains.` The domain must serve the Apple Pay verification file at the well-known path before it is accepted.

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

Yes. Jentic One is self-hosted, so you set the rules that decide which MONEI operations and credentials your agent may use. You choose the exact operations it can call, so a destructive one like POST `/payments/{id}/refund` is left out unless you add it, while it still creates and retrieves payments. Because MONEI puts the payment id in the URL path, such as `/payments/{id}` and `/payments/{id}/refund`, you can also pin the agent to a single payment and only the operations you permit on it.