# Checkout.com MCP for AI Agents MCP

> Checkout.com MCP lets you manage complex global payment operations directly through your AI client. Handle everything from initiating payments and capturing funds to issuing refunds or voiding transactions—all without leaving your chat window. It gives your agent full control over vault instruments, payment history, and detailed billing records right where you're working.

## Overview
- **Category:** money-moves
- **Price:** Free
- **Tags:** payment-vaulting, card-processing, transaction-management, fintech, api-payments

## Description

Managing global money moves used to mean jumping between multiple dashboards: one for authorization, another for vaulting cards, and a third just to check the status of a refund. This MCP changes that entirely. You connect your Checkout.com account once, giving your AI client direct access to core payment logic. It handles everything from requesting initial payments and capturing those funds to securely managing customer instruments in the Vault. Need to fix an error? Your agent can retrieve detailed payment actions or audit historical billing data instantly. Everything is managed via natural conversation—whether you're debugging a complex instrument update, processing a batch of refunds, or simply checking why a transaction failed. If you already use Vinkius as your central hub for connecting different services, adding this MCP means all your financial operations run through one place.

## Tools

### capture_payment
Finalizes an authorized payment by locking the funds into settled limits and verifying the capture process.

### create_instrument
Adds a new, highly available customer card record to the Vault system for future use.

### delete_instrument
Permanently removes an instrument from the Vault after irreversible validation steps.

### get_payment_actions
Lists all structured rules attached to a payment, showing its current gateway status and history.

### get_instrument
Retrieves details on specific card records currently stored in the Vault logic.

### get_payment_details
Pulls out all key data points related to a payment, crucial for understanding its current billing status.

### refund_payment
Sends money back to the original cardholder and automatically validates any required clawback logic for the refund.

### request_payment
Identifies customer records that can be used as a payment source within the Checkout.com Gateway.

### update_instrument
Modifies an existing card record in the Vault, which is useful for updating holder names or expiry dates.

### void_payment
Cancels a payment authorization before capture occurs, preventing unnecessary gateway fees and closing limits.

## Prompt Examples

**Prompt:** 
```
A customer claims they were charged twice for the same service last month.
```

**Response:** 
```
**Billing Audit Report: pay_789**

*   **Transaction ID:** pay_789
*   **Status:** Captured (Success)
*   **Amount:** $120.00 USD
*   **Action History:** Authorized 10/15; Captured 10/16.

We found a second transaction, pay_990. It was voided on 11/1 last week because the billing address didn't match the vault record. You should run `get_payment_actions` to confirm this history.
```

**Prompt:** 
```
I need to process a refund for an order that happened three months ago.
```

**Response:** 
```
**Refund Request Status**

✅ Refund initiated for payment ID: pay_456.
*   **Amount:** $75.00 USD
*   **Target Network:** Visa/MC
*   **Status:** Processing (Clawback logic verified).

Please allow 3-5 business days for the funds to appear on the original account.
```

**Prompt:** 
```
Can we add a new card for John Doe and make sure it's ready for payments?
```

**Response:** 
```
**Instrument Provisioning Complete**

The instrument record was successfully created in the Vault.

*   **Holder Name:** John Doe
*   **Card Type:** Visa
*   **Last 4 Digits:** 5678
*   **Status:** Active and ready for use with `request_payment`.
```

## Capabilities

### Process and finalize payments
Your agent can initiate payment requests, capture authorized funds to settle them, or void transactions before the final settlement.

### Manage stored customer card data
You can provision new payment instruments, update existing ones, or delete records held in the Checkout.com Vault safely.

### Audit and track transaction history
The system provides a full log of all actions taken on payments, helping you pinpoint exactly where an authorization succeeded or failed.

### Execute refunds and clawbacks
You can automatically route refunds back to the originating Visa/MC network while validating any potential clawback logic required by the transaction rules.

### Retrieve payment details for billing checks
It extracts specific properties of a payment, giving you all the necessary data points needed for reconciliation or debugging.

## Use Cases

### Customer calls about a missing refund
A support agent asks their AI client, 'What's the status of payment pay_123?' The agent uses `get_payment_details` and reports back immediately if the refund was successfully processed via `refund_payment`, resolving the customer query in minutes.

### Debugging a failed batch capture
A developer needs to know why some payments authorized yesterday didn't settle. They use their agent to check all payment actions for a range of IDs, pinpointing the exact failure code using `get_payment_actions`.

### Updating a customer's saved card details
The operations team needs to change the billing address and name on an existing customer card. They use their agent to call `update_instrument` directly, ensuring the Vault record is current for the next sale.

### Preemptively canceling pending charges
Before a client leaves your service, you need to ensure all temporary holds are released. You instruct your agent to run `void_payment` on specific transactions, immediately freeing up gateway limits and preventing unnecessary fees.

## Benefits

- Stop jumping between dashboards. Use this MCP to manage payment actions like `refund_payment` or `void_payment` entirely within your agent conversation.
- Maintain a clean audit trail of all funds. Run `get_payment_actions` whenever you need to understand exactly why an authorization succeeded or failed months later.
- Handle card data securely and efficiently. Use `create_instrument` and `update_instrument` to keep customer payment details current without manual data entry.
- Speed up reconciliation. With simple calls like `get_payment_details`, you get the exact properties needed for finance teams to verify billing records quickly.
- Reduce development time. Developers can test complex payment flows in sandbox using tools like `request_payment` and `capture_payment` via natural language prompts.

## How It Works

The bottom line is that once it’s connected, your agent handles all the API calls for payments and vaulting so you don't have to write any code.

1. First, subscribe to this MCP on Vinkius and provide your Checkout.com Secret API Key.
2. Next, select whether you're working in the Sandbox (for testing) or the Live environment.
3. Finally, start asking your AI client to perform payment actions via natural language conversation.

## Frequently Asked Questions

**How do I handle refunds using the Checkout.com MCP for AI Agents?**
You simply ask your agent to refund a specific payment ID and amount. The tool handles all the necessary validation, ensuring that any required clawback logic is applied before sending the money back to the cardholder.

**Can I update customer card details using this MCP?**
Yes, you can manage the Vault by updating instruments. You tell your agent which card needs changing and what the new details are, like a name or address, and it handles the secure record modification.

**What if I need to cancel an authorization before payment?**
You run the void function on the specific transaction ID. This cancels the authorized hold, immediately removing the limit from your gateway account and preventing fees.

**Does this MCP help me audit failed payments?**
Absolutely. You can use the payment actions tool to look up a payment ID and get an exhaustive list of all events that happened, telling you exactly why the bank declined or rejected the transaction.

**Is this MCP for AI Agents good for e-commerce billing?**
It's ideal for e-commerce. You can manage the entire payment lifecycle—from initial request to final refund—all in one place, drastically reducing manual effort and improving reconciliation accuracy.

**Can I test payments without using real money?**
Yes. When setting up your MCP, you choose between Sandbox or Live mode. You can safely run all tests on the sandbox environment until everything is perfect.