The SolvaPay MCP Server gives AI agents — and any MCP-compatible client — full
programmatic access to your SolvaPay account. Every tool follows a consistent
request/response pattern and accepts JSON parameters as described below.
Parameters marked Required must always be provided. Optional parameters can
be omitted and will either use a sensible default or be ignored.
| Domain | Tools | Count |
|---|
| Customer Management | create_customer · get_customer · list_customers · update_customer · delete_customer · ensure_customer | 6 |
| Product Management | create_product · get_product · list_products · update_product · delete_product | 5 |
| Purchase Management | list_purchases · get_purchase · get_purchases_by_customer · get_purchases_by_product · cancel_renewal · check_limits | 6 |
| Payment & Checkout | create_checkout_session · create_customer_session | 2 |
| Wallet & Revenue | get_product_balance | 1 |
| Usage Tracking | record_usage · record_bulk_usage | 2 |
| Transactions & Refunds | list_transactions · get_transaction · get_transaction_stats · create_refund | 4 |
| Total | 26 |
Customer Management
| Tool | Description |
|---|
create_customer | Create a new customer |
get_customer | Retrieve a customer by reference |
list_customers | List customers with search and pagination |
update_customer | Update a customer’s details |
delete_customer | Delete a customer |
ensure_customer | Create or retrieve a customer by email (idempotent) |
create_customer
| Parameter | Type | Required | Description |
|---|
email | string | Yes | Customer email address |
name | string | No | Customer display name |
telephone | string | No | Customer telephone number |
metadata | object | No | Arbitrary key-value metadata |
get_customer
| Parameter | Type | Required | Description |
|---|
reference | string | Yes | Customer reference (e.g. cus_A1B2C3D4) |
list_customers
| Parameter | Type | Required | Default | Description |
|---|
limit | number | No | 20 | Maximum results to return |
offset | number | No | 0 | Pagination offset |
search | string | No | — | Search by name or email |
update_customer
| Parameter | Type | Required | Description |
|---|
reference | string | Yes | Customer reference |
name | string | No | Updated name |
email | string | No | Updated email |
telephone | string | No | Updated telephone |
metadata | object | No | Updated metadata |
delete_customer
| Parameter | Type | Required | Description |
|---|
reference | string | Yes | Customer reference |
ensure_customer
Creates a customer if one doesn’t exist for the given email. Returns the existing customer if found.
| Parameter | Type | Required | Description |
|---|
email | string | Yes | Customer email (used as unique key) |
name | string | No | Customer name (used only on creation) |
externalRef | string | No | Your system’s ID for this customer |
Product Management
| Tool | Description |
|---|
create_product | Create a new product |
get_product | Retrieve a product by reference |
list_products | List products with search and filters |
update_product | Update a product’s details |
delete_product | Delete a product |
create_product
| Parameter | Type | Required | Description |
|---|
name | string | Yes | Product name |
description | string | No | Product description |
get_product
| Parameter | Type | Required | Description |
|---|
reference | string | Yes | Product reference (e.g. prd_P9Q0R1S2) |
list_products
| Parameter | Type | Required | Default | Description |
|---|
limit | number | No | 20 | Maximum results |
offset | number | No | 0 | Pagination offset |
search | string | No | — | Search by name |
status | string | No | — | Filter by status |
update_product
| Parameter | Type | Required | Description |
|---|
reference | string | Yes | Product reference |
name | string | No | Updated name |
description | string | No | Updated description |
delete_product
| Parameter | Type | Required | Description |
|---|
reference | string | Yes | Product reference |
Purchase Management
| Tool | Description |
|---|
list_purchases | List all purchases |
get_purchase | Retrieve a purchase by ID |
get_purchases_by_customer | Purchases for a customer |
get_purchases_by_product | Purchases for a product |
cancel_renewal | Cancel renewal of a purchase |
check_limits | Check usage limits for a customer/product pair |
list_purchases
| Parameter | Type | Required | Description |
|---|
status | string | No | Filter by status |
get_purchase
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Purchase ID or reference |
get_purchases_by_customer
| Parameter | Type | Required | Description |
|---|
customerRef | string | Yes | Customer reference |
status | string | No | Filter by status |
get_purchases_by_product
| Parameter | Type | Required | Description |
|---|
productRef | string | Yes | Product reference |
status | string | No | Filter by status |
cancel_renewal
| Parameter | Type | Required | Description |
|---|
purchaseId | string | Yes | Purchase ID or reference |
reason | string | No | Cancellation reason |
check_limits
Returns usage-limit status for a customer/product pair. If limits are exceeded, the response includes a checkout URL for the customer to upgrade.
| Parameter | Type | Required | Description |
|---|
customerRef | string | Yes | Customer reference |
productRef | string | Yes | Product reference |
Payment & Checkout
| Tool | Description |
|---|
create_checkout_session | Generate a checkout URL |
create_customer_session | Generate a customer billing-portal URL |
create_checkout_session
| Parameter | Type | Required | Description |
|---|
customerRef | string | Yes | Customer reference |
productRef | string | Yes | Product reference |
planRef | string | No | Plan reference (uses the product’s default plan if omitted) |
returnUrl | string | No | Redirect URL after checkout completes |
create_customer_session
Generates a URL where the customer can manage their billing, payment methods, and purchases.
| Parameter | Type | Required | Description |
|---|
customerRef | string | Yes | Customer reference |
Wallet & Revenue
| Tool | Description |
|---|
get_product_balance | Get revenue for a specific product |
get_product_balance
| Parameter | Type | Required | Description |
|---|
productRef | string | Yes | Product reference |
Usage Tracking
| Tool | Description |
|---|
record_usage | Record a single usage event |
record_bulk_usage | Record multiple usage events in one call |
record_usage
| Parameter | Type | Required | Description |
|---|
customerRef | string | Yes | Customer reference |
productRef | string | Yes | Product reference |
outcome | string | Yes | Outcome identifier (e.g. success, failure) |
action | string | No | Action name |
requestId | string | No | Idempotency / correlation ID |
actionDuration | number | No | Duration in milliseconds |
record_bulk_usage
| Parameter | Type | Required | Description |
|---|
events | array | Yes | Array of usage-event objects (same schema as record_usage) |
events accepts the same fields as record_usage.
Transactions & Refunds
| Tool | Description |
|---|
list_transactions | List transactions with filters |
get_transaction | Retrieve a transaction by ID |
get_transaction_stats | Get transaction count and statistics |
create_refund | Refund a transaction (full or partial) |
list_transactions
| Parameter | Type | Required | Default | Description |
|---|
limit | number | No | 20 | Maximum results |
offset | number | No | 0 | Pagination offset |
status | string | No | — | Filter by status |
fromDate | string | No | — | Start date (ISO 8601) |
toDate | string | No | — | End date (ISO 8601) |
get_transaction
| Parameter | Type | Required | Description |
|---|
transactionId | string | Yes | Transaction ID |
get_transaction_stats
| Parameter | Type | Required | Description |
|---|
fromDate | string | No | Start date (ISO 8601) |
toDate | string | No | End date (ISO 8601) |
create_refund
| Parameter | Type | Required | Description |
|---|
sourceTransactionId | string | Yes | Transaction ID to refund |
amount | number | No | Partial refund amount (omit for a full refund) |
reason | string | No | Refund reason |
