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

# PayPlug Payments API

Jentic publishes the only available OpenAPI specification for PayPlug Payments API, keeping it validated and agent-ready. PayPlug is a French payment processor that enables merchants to accept card payments, process refunds, manage stored cards, and offer installment payment plans. The API provides 11 endpoints covering the full payment lifecycle from creation through refund and supports French market features like 3x/4x installment plans (paiement en plusieurs fois).

## For AI agents

Accept card payments, process refunds, manage stored cards, and create installment payment plans for French and European merchants.

## Scope

Does not handle bank transfers, direct debits, or multi-country payment routing - use for card payments, refunds, and installment plans in the French market only.

## Capabilities

- Accept card payments with 3D Secure authentication and hosted payment pages
- Process full and partial refunds against completed payments
- Store and manage customer card details for repeat purchases
- Create installment payment plans (3x or 4x) for higher-value transactions
- Retrieve payment and refund details with full transaction metadata
- Track installment plan status and individual installment completion

## Use cases

### French E-Commerce Payment Acceptance

Accept card payments from French and European customers through PayPlug's payment gateway. The API supports hosted payment pages with 3D Secure authentication, reducing PCI compliance burden. Payments are created via API and the customer completes authentication on a PayPlug-hosted page before the merchant receives confirmation.

Example prompt: Create a payment for 149.99 EUR via POST `/v1/payments` with a return URL and hosted_payment configuration, then retrieve the payment status

### Installment Payment Plans

Offer customers the option to pay in 3 or 4 installments (paiement en plusieurs fois) for higher-value purchases. PayPlug manages the installment schedule, collects each payment automatically, and handles failures. This French-market feature increases conversion rates on expensive items by splitting the total across multiple monthly payments.

Example prompt: Create a 3-installment plan for 299.99 EUR via POST `/v1/installment_plans` and monitor the plan status via GET `/v1/installment_plans/{installmentPlanId}`

### Automated Refund Processing

Issue refunds against completed PayPlug payments programmatically. The API supports both full refunds (refunding the entire payment amount) and partial refunds. Each refund is tracked independently and linked to the original payment for reconciliation.

Example prompt: Issue a partial refund of 25.00 EUR against payment ID pay_abc123 via POST `/v1/payments/{paymentId}/refunds`

### AI Agent Payment Orchestration

AI agents use the PayPlug API through Jentic to process French payments, manage installment plans, and handle refunds without managing bearer token lifecycle or payment page flows directly. Jentic handles credential isolation and operation discovery for all 11 PayPlug endpoints.

Example prompt: Search Jentic for 'create a payment in France', load the PayPlug payment creation schema, and execute a 79.99 EUR card payment

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/payments` | Create a new payment |
| GET | `/v1/payments/{paymentId}` | Retrieve payment details |
| POST | `/v1/payments/{paymentId}/refunds` | Issue a refund |
| GET | `/v1/payments/{paymentId}/refunds/{refundId}` | Get refund details |
| GET | `/v1/cards/{cardId}` | Retrieve stored card details |
| POST | `/v1/installment_plans` | Create an installment plan |
| GET | `/v1/installment_plans/{installmentPlanId}` | Get installment plan status |

## Key resources

- **Payments** — Create payments, retrieve details, and manage payment lifecycle
- **Refunds** — Issue and retrieve refunds against completed payments
- **Cards** — Retrieve stored card details for returning customers
- **Installment Plans** — Create and manage installment payment plans

## Why Jentic

- **Setup:** Wiring PayPlug by hand means learning its bearer auth with your secret key and coding calls against payments, refunds, and installment plans for the French market yourself. Through Jentic you install once, import PayPlug from the API Directory, store the secret key once, and your agent calls it.
- **Permission scoping:** PayPlug puts the payment id in the URL path (`/v1/payments/{paymentId}/refunds`), so a rule can pin your agent to one payment: it can read that payment and its refunds and nothing else. You choose the operations it may call, so creating payments or issuing refunds is not included unless you add them.
- **Credential handling:** Your PayPlug secret key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an installment plan in France' or 'refund a card payment', and Jentic returns the matching PayPlug operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe** — Global payment processor with French market support and broader feature set
- **Mollie** — European payment gateway focused on Western European markets
- **Adyen Payment Service** — Enterprise payment platform with omnichannel capabilities

## FAQ

### Why is there no official OpenAPI spec for PayPlug Payments API?

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

The PayPlug API uses Bearer token authentication with your secret API key sent in the Authorization header. Through Jentic, API keys are stored encrypted in your Jentic One instance and agents receive scoped access without handling raw secret keys.

### Can I offer installment payments (3x or 4x) with PayPlug?

Yes. The POST `/v1/installment_plans` endpoint creates a payment plan that splits the total amount across 3 or 4 monthly installments. PayPlug manages the collection schedule automatically and you can monitor progress via GET `/v1/installment_plans/{installmentPlanId}.`

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

Use Jentic to search for 'refund a PayPlug payment', load the schema for POST `/v1/payments/{paymentId}/refunds`, and execute with the refund amount. The response includes the refund ID and status. You can also retrieve refund details via GET `/v1/payments/{paymentId}/refunds/{refundId}.`

### Does PayPlug support 3D Secure authentication?

Yes. PayPlug payments support 3D Secure (3DS) authentication for Strong Customer Authentication (SCA) compliance. When creating a payment via POST `/v1/payments`, you configure the hosted payment page which handles the 3DS challenge flow automatically.

### Can I store customer cards for repeat purchases?

Yes. PayPlug stores card details securely and provides the GET `/v1/cards/{cardId}` endpoint to retrieve card information for returning customers. Stored cards can be used to create subsequent payments without the customer re-entering their card details.

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

Yes. Jentic One runs self-hosted in your own instance, so your rules decide which PayPlug operations the agent may call and which credentials it may use. Because PayPlug puts the payment id in the URL path, such as GET `/v1/payments/{paymentId}/refunds`, you can pin the agent to a single payment so it only reads that payment and its refunds. You choose the operations it may call, so creating payments through POST `/v1/payments` or issuing refunds through POST `/v1/payments/{paymentId}/refunds` stays off limits until you add it.