> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tool Reference

> Formal specifications for all Yuno MCP tools including schemas, dependencies, and error handling

## Overview

This reference documents every MCP tool exposed by the Yuno MCP server. Each tool maps to a Yuno API endpoint and follows the [Model Context Protocol](https://modelcontextprotocol.io) specification.

<Note>
  Underlying REST calls use the same authentication as the public API: `public-api-key` and `private-secret-key` headers, plus `account_id` in the body on endpoints that take it. The MCP server reads sandbox credentials from its own environment variables (see [LLM & MCP integration](/ai/llm-mcp-integration)).
</Note>

<a href="/diagrams/state-and-architecture/tool-dependency-graph.html" target="_blank" style={{ display: 'block', cursor: 'zoom-in', textDecoration: 'none' }}>
  <div style={{ position: 'relative', width: '100%', paddingBottom: '56.75%', overflow: 'hidden', borderRadius: '12px', boxShadow: '0 4px 24px rgba(0,0,0,0.08)' }}>
    <iframe src="/diagrams/state-and-architecture/tool-dependency-graph.html" style={{ position: 'absolute', top: 0, left: 0, width: '1540px', height: '874px', border: 'none', transform: 'scale(0.455)', transformOrigin: 'top left' }} loading="lazy" />
  </div>
</a>

<Note>
  MCP tools are designed for sandbox use during development and debugging. All tool calls count against your standard API rate limits.
</Note>

***

## Tool Summary

| Tool                      | Operation                  | API Endpoint                 | Method |
| ------------------------- | -------------------------- | ---------------------------- | ------ |
| `create_checkout_session` | Start a payment flow       | `/v1/checkout/sessions`      | POST   |
| `create_payment`          | Process a payment          | `/v1/payments`               | POST   |
| `get_payment`             | Retrieve payment details   | `/v1/payments/{id}`          | GET    |
| `list_payments`           | List recent payments       | `/v1/payments`               | GET    |
| `capture_payment`         | Capture authorized payment | `/v1/payments/{id}/capture`  | POST   |
| `cancel_payment`          | Cancel a payment           | `/v1/payments/{id}/cancel`   | POST   |
| `create_refund`           | Refund a payment           | `/v1/payments/{id}/refund`   | POST   |
| `get_payment_methods`     | List available methods     | `/v1/checkout/sessions/{id}` | GET    |
| `validate_payload`        | Pre-flight validation      | Client-side                  | N/A    |
| `create_customer`         | Create customer record     | `/v1/customers`              | POST   |
| `get_customer`            | Retrieve customer          | `/v1/customers/{id}`         | GET    |
| `create_recipient`        | Create payout recipient    | `/v1/recipients`             | POST   |
| `create_payout`           | Send funds to recipient    | `/v1/payouts`                | POST   |

***

## Tool Dependency Matrix

Some tools require outputs from other tools. This matrix shows prerequisites.

| Tool                      | Requires                                  | Provides                  |
| ------------------------- | ----------------------------------------- | ------------------------- |
| `create_checkout_session` | None                                      | `checkout_session` (UUID) |
| `create_payment`          | `checkout_session`                        | `payment_id` (UUID)       |
| `get_payment`             | `payment_id`                              | Payment status, details   |
| `list_payments`           | None                                      | Array of payment objects  |
| `capture_payment`         | `payment_id` (status: AUTHORIZED)         | Updated payment           |
| `cancel_payment`          | `payment_id` (status: AUTHORIZED/PENDING) | Updated payment           |
| `create_refund`           | `payment_id` (status: SUCCEEDED)          | Updated payment           |
| `get_payment_methods`     | `checkout_session`                        | Available payment methods |
| `validate_payload`        | None                                      | Validation result         |
| `create_customer`         | None                                      | `customer_id` (UUID)      |
| `get_customer`            | `customer_id`                             | Customer details          |
| `create_recipient`        | None                                      | `recipient_id` (UUID)     |
| `create_payout`           | `recipient_id`                            | `payout_id` (UUID)        |

### Calling Order for Common Flows

**Standard payment:** `create_checkout_session` -> `create_payment` -> `get_payment`

**Auth + capture:** `create_checkout_session` -> `create_payment` -> `capture_payment`

**Refund:** `get_payment` (verify status) -> `create_refund`

**Payout:** `create_recipient` -> `create_payout`

***

## Tool Specifications

### create\_checkout\_session

Creates a new checkout session to initialize a payment flow.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["amount", "country", "merchant_order_id"],
  "properties": {
    "amount": {
      "type": "object",
      "required": ["currency", "value"],
      "properties": {
        "currency": { "type": "string", "description": "ISO 4217 code (e.g., USD, BRL, COP, MXN)" },
        "value": { "type": "number", "description": "Amount in major currency units" }
      }
    },
    "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2" },
    "merchant_order_id": { "type": "string", "description": "Your unique order reference" },
    "payment_description": { "type": "string" },
    "customer_id": { "type": "string", "format": "uuid" },
    "workflow": { "type": "string", "enum": ["SDK_CHECKOUT", "SDK_LITE", "DIRECT"] }
  }
}
```

**Output Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "properties": {
    "checkout_session": { "type": "string", "format": "uuid" },
    "amount": { "$ref": "Amount" },
    "country": { "type": "string" },
    "merchant_order_id": { "type": "string" },
    "status": { "type": "string" },
    "created_at": { "type": "string", "format": "date-time" },
    "payment_methods": { "type": "array" }
  }
}
```

**Rate limit:** 100 requests per 60 seconds

**Idempotency:** Not idempotent. Each call creates a new session. Use unique `merchant_order_id` values.

**Error codes:**

| Code                | HTTP | Description                                                                 | Action                                                     |
| ------------------- | ---- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `VALIDATION_ERROR`  | 400  | Schema or constraint validation failed. `messages` names the failed fields. | Fix the named fields, retry.                               |
| `INVALID_REQUEST`   | 400  | Request rejected by business rules.                                         | Fix the payload, retry.                                    |
| `UNAUTHORIZED`      | 401  | Missing or invalid `public-api-key` / `private-secret-key`.                 | Verify the headers.                                        |
| `TOO_MANY_REQUESTS` | 429  | Edge throttling.                                                            | Exponential backoff with full jitter. Honor `Retry-After`. |
| `INTERNAL_ERROR`    | 500  | Server side error.                                                          | Retry with backoff.                                        |

***

### create\_payment

Creates a payment against an existing checkout session.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["checkout_session", "payment_method", "amount", "country"],
  "properties": {
    "checkout_session": { "type": "string", "format": "uuid" },
    "payment_method": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": { "type": "string", "enum": ["CARD", "PIX", "BOLETO", "PSE", "SPEI", "OXXO", "BNPL", "GOOGLE_PAY", "APPLE_PAY"] },
        "token": { "type": "string", "description": "Tokenized card payment method" },
        "vaulted_token": { "type": "string", "description": "Stored payment method for returning customers" }
      }
    },
    "amount": { "$ref": "Amount" },
    "country": { "type": "string", "pattern": "^[A-Z]{2}$" },
    "customer": {
      "type": "object",
      "properties": {
        "document": { "$ref": "CustomerDocument" },
        "email": { "type": "string", "format": "email" },
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "phone": { "type": "string" }
      }
    },
    "description": { "type": "string" },
    "installments": { "type": "integer", "minimum": 1 }
  }
}
```

**Output Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "checkout_session": { "type": "string", "format": "uuid" },
    "status": { "type": "string", "enum": ["SUCCEEDED", "PENDING", "DECLINED", "REJECTED", "AUTHORIZED"] },
    "amount": { "$ref": "Amount" },
    "country": { "type": "string" },
    "payment_method": { "type": "object" },
    "provider": { "type": "object" },
    "merchant_order_id": { "type": "string" },
    "created_at": { "type": "string", "format": "date-time" },
    "updated_at": { "type": "string", "format": "date-time" }
  }
}
```

**Rate limit:** 100 requests per 60 seconds

**Idempotency:** One payment per checkout session. Submitting a second payment to the same session returns an error.

**Parameter validation rules:**

* `checkout_session` must reference an ACTIVE session
* `amount` must match the session amount
* `country` must match the session country
* PIX payments in BR require `customer.document` (CPF or CNPJ)
* CARD payments require either `token` or `vaulted_token`
* `installments` only applies to CARD payments

**Error codes:**

| `code`                                | HTTP | Description                                                               | Action                                             |
| ------------------------------------- | ---- | ------------------------------------------------------------------------- | -------------------------------------------------- |
| `VALIDATION_ERROR`                    | 400  | Required field missing or malformed. `messages` names every failed field. | Fix the named fields and retry.                    |
| `INVALID_REQUEST`                     | 400  | Request rejected by business rules.                                       | Fix the payload according to `messages` and retry. |
| `PROVIDER_UNAVAILABLE_PAYMENT_METHOD` | 400  | The selected method is not available on the routed provider.              | Enable the method or pick another.                 |
| `PROVIDER_INVALID_REQUEST`            | 400  | Provider rejected the transaction.                                        | Check the provider response in `messages`.         |
| `TOO_MANY_REQUESTS`                   | 429  | Edge throttling.                                                          | Retry with exponential backoff and full jitter.    |

***

### get\_payment

Retrieves payment details by ID. Use for polling payment status.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["payment_id"],
  "properties": {
    "payment_id": { "type": "string", "format": "uuid" }
  }
}
```

**Output Schema:** Same as `create_payment` output.

**Rate limit:** Standard API limits

**Idempotency:** Safe to call repeatedly (GET request).

**Error codes:**

| Code        | HTTP | Description               | Action                 |
| ----------- | ---- | ------------------------- | ---------------------- |
| `NOT_FOUND` | 404  | Payment ID does not exist | Verify the payment\_id |

***

### list\_payments

Returns a paginated list of payments.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "properties": {
    "limit": { "type": "integer", "default": 20, "maximum": 100 },
    "starting_after": { "type": "string", "description": "Payment ID cursor for forward pagination" },
    "ending_before": { "type": "string", "description": "Payment ID cursor for backward pagination" }
  }
}
```

**Output Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "array",
  "items": { "$ref": "Payment" }
}
```

**Rate limit:** 100 requests per 60 seconds

**Idempotency:** Safe to call repeatedly (GET request).

***

### capture\_payment

Captures a previously authorized payment. Only valid for payments in `AUTHORIZED` status.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["payment_id"],
  "properties": {
    "payment_id": { "type": "string", "format": "uuid" },
    "amount": {
      "type": "object",
      "properties": {
        "currency": { "type": "string" },
        "value": { "type": "number", "description": "Capture amount. Must be <= authorized amount." }
      }
    }
  }
}
```

**Output Schema:** Same as `create_payment` output (status changes to `SUCCEEDED`).

**Parameter validation rules:**

* Payment must be in `AUTHORIZED` status
* Capture amount must not exceed authorized amount
* Partial capture is supported (amount \< authorized amount)

**Error codes:**

| Code              | HTTP | Description                                        | Action                      |
| ----------------- | ---- | -------------------------------------------------- | --------------------------- |
| `INVALID_STATE`   | 400  | Payment not in AUTHORIZED status                   | Verify payment status first |
| `INVALID_REQUEST` | 400  | Capture amount greater than the authorized amount. | Reduce capture amount.      |

***

### cancel\_payment

Cancels a pending or authorized payment.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["payment_id"],
  "properties": {
    "payment_id": { "type": "string", "format": "uuid" }
  }
}
```

**Output Schema:** Same as `create_payment` output (status changes to `CANCELLED`).

**Error codes:**

| Code            | HTTP | Description                                  | Action                                    |
| --------------- | ---- | -------------------------------------------- | ----------------------------------------- |
| `INVALID_STATE` | 400  | Payment cannot be cancelled in current state | Use refund instead for SUCCEEDED payments |

***

### create\_refund

Refunds a completed payment. Supports full and partial refunds.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["payment_id"],
  "properties": {
    "payment_id": { "type": "string", "format": "uuid" },
    "amount": {
      "type": "object",
      "description": "Omit for full refund",
      "properties": {
        "currency": { "type": "string" },
        "value": { "type": "number" }
      }
    },
    "reason": { "type": "string" }
  }
}
```

**Output Schema:** Same as `create_payment` output (status changes to `REFUNDED` or `PARTIALLY_REFUNDED`).

**Parameter validation rules:**

* Payment must be in `SUCCEEDED` or `PARTIALLY_REFUNDED` status
* Refund amount must not exceed remaining refundable balance
* Omitting `amount` triggers a full refund

**Error codes:**

| Code              | HTTP | Description                              | Action                |
| ----------------- | ---- | ---------------------------------------- | --------------------- |
| `INVALID_STATE`   | 400  | Payment not refundable                   | Verify payment status |
| `INVALID_REQUEST` | 400  | Refund amount exceeds remaining balance. | Reduce refund amount. |

***

### validate\_payload

Client-side validation tool that checks a payment payload against Yuno's schema without making an API call.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["payload", "operation"],
  "properties": {
    "payload": { "type": "object", "description": "The request body to validate" },
    "operation": {
      "type": "string",
      "enum": ["createCheckoutSession", "createPayment", "createRefund", "createPayout"],
      "description": "The operation this payload is intended for"
    }
  }
}
```

**Output Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "properties": {
    "valid": { "type": "boolean" },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": { "type": "string" },
          "message": { "type": "string" },
          "expected": { "type": "string" }
        }
      }
    }
  }
}
```

**Rate limit:** No API call made; unlimited.

**Idempotency:** Stateless; always safe to call.

***

### create\_customer

Creates a customer record for use in checkout sessions.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["email"],
  "properties": {
    "email": { "type": "string", "format": "email" },
    "first_name": { "type": "string" },
    "last_name": { "type": "string" },
    "phone": { "type": "string" },
    "document": { "$ref": "CustomerDocument" },
    "merchant_customer_id": { "type": "string" }
  }
}
```

**Output Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string" },
    "first_name": { "type": "string" },
    "last_name": { "type": "string" },
    "phone": { "type": "string" },
    "document": { "$ref": "CustomerDocument" },
    "merchant_customer_id": { "type": "string" },
    "created_at": { "type": "string", "format": "date-time" }
  }
}
```

**Error codes:**

| Code              | HTTP | Description                      | Action                |
| ----------------- | ---- | -------------------------------- | --------------------- |
| `INVALID_REQUEST` | 400  | Invalid email or document format | Fix field format      |
| `DUPLICATE`       | 400  | Customer with same email exists  | Use existing customer |

***

### create\_recipient

Creates a payout recipient with bank account details.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["merchant_recipient_id", "country"],
  "properties": {
    "merchant_recipient_id": { "type": "string" },
    "country": { "type": "string", "pattern": "^[A-Z]{2}$" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "document": { "$ref": "CustomerDocument" },
    "bank_account": {
      "type": "object",
      "properties": {
        "bank_code": { "type": "string" },
        "account_number": { "type": "string" },
        "account_type": { "type": "string", "enum": ["CHECKING", "SAVINGS"] }
      }
    }
  }
}
```

**Output Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "merchant_recipient_id": { "type": "string" },
    "country": { "type": "string" },
    "name": { "type": "string" },
    "bank_account": { "type": "object" },
    "created_at": { "type": "string", "format": "date-time" }
  }
}
```

***

### create\_payout

Sends funds to a previously created recipient.

**Input Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "required": ["amount", "country", "recipient_id"],
  "properties": {
    "amount": { "$ref": "Amount" },
    "country": { "type": "string", "pattern": "^[A-Z]{2}$" },
    "recipient_id": { "type": "string", "format": "uuid" },
    "description": { "type": "string" },
    "merchant_reference": { "type": "string" },
    "purpose": { "type": "string" }
  }
}
```

**Output Schema:**

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "status": { "type": "string", "enum": ["PENDING", "SUCCEEDED", "FAILED", "CANCELLED"] },
    "amount": { "$ref": "Amount" },
    "recipient_id": { "type": "string" },
    "created_at": { "type": "string", "format": "date-time" }
  }
}
```

***

## Multi-Step Examples

### Example: Complete Payment Flow

```
Step 1: Agent calls create_checkout_session
  Input:  { amount: { currency: "USD", value: 99.90 }, country: "US", merchant_order_id: "order-123" }
  Output: { checkout_session: "sess_abc123", status: "ACTIVE", payment_methods: [...] }

Step 2: Agent calls create_payment
  Input:  { checkout_session: "sess_abc123", payment_method: { type: "CARD", token: "tok_test_abc" }, amount: { currency: "USD", value: 99.90 }, country: "US", customer: { email: "dee@hock.example", first_name: "Jane", last_name: "Smith" } }
  Output: { id: "pay_def456", status: "SUCCEEDED" }

Step 3: Agent calls get_payment (polling)
  Input:  { payment_id: "pay_def456" }
  Output: { id: "pay_def456", status: "SUCCEEDED" }
```

### Example: Validate then Create

```
Step 1: Agent calls validate_payload
  Input:  { payload: { amount: { currency: "USD" }, country: "US" }, operation: "createCheckoutSession" }
  Output: { valid: false, errors: [{ field: "amount.value", message: "Required field missing" }, { field: "merchant_order_id", message: "Required field missing" }] }

Step 2: Agent fixes payload and calls create_checkout_session
  Input:  { amount: { currency: "USD", value: 50.00 }, country: "US", merchant_order_id: "order-456" }
  Output: { checkout_session: "sess_ghi789", status: "ACTIVE" }
```

***

## Rate Limiting

All MCP tools that make API calls share the same rate limits as direct API access.

| Endpoint Group             | Limit    | Window     | Scope       |
| -------------------------- | -------- | ---------- | ----------- |
| Checkout Sessions (create) | 100      | 60 seconds | Per API key |
| Payments (create)          | 100      | 60 seconds | Per API key |
| Payments (list)            | 100      | 60 seconds | Per API key |
| All other endpoints        | Standard | Standard   | Per API key |

When rate limited (HTTP 429), implement exponential backoff:

```
Retry 1: wait 1 second
Retry 2: wait 2 seconds
Retry 3: wait 4 seconds
Maximum retries: 3
```