KosmoKrator

finance

Mercado Pago Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Mercado Pago KosmoKrator integration.

7 functions 6 read 1 write Bearer token auth
Submit Mercado Pago feedback View package source

Lua Namespace

Agents call this integration through app.integrations.mercado_pago.*. Use lua_read_doc("integrations.mercado-pago") inside KosmoKrator to discover the same reference at runtime.

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Mercado Pago — Lua API Reference

list_payments

Search and list payments from Mercado Pago with optional filters.

Parameters

NameTypeRequiredDescription
limitintegernoMax results (default: 30, max: 1000)
offsetintegernoNumber of results to skip (default: 0)
external_referencestringnoFilter by your custom external reference
statusstringnoPayment status filter (see values below)
date_created_fromstringnoCreated after (ISO 8601, e.g., "2025-01-01T00:00:00.000-00:00")
date_created_tostringnoCreated before (ISO 8601, e.g., "2025-12-31T23:59:59.999-00:00")

Payment Status Values

pending, approved, authorized, in_process, in_mediation, rejected, cancelled, refunded, charged_back

Example

local result = app.integrations["mercado-pago"].list_payments({
  status = "approved",
  limit = 10
})

for _, payment in ipairs(result.results) do
  print(payment.id .. ": " .. payment.transaction_amount .. " " .. payment.currency_id)
end

get_payment

Retrieve full details of a specific payment.

Parameters

NameTypeRequiredDescription
idstringyesMercado Pago payment ID

Example

local result = app.integrations["mercado-pago"].get_payment({
  id = "1234567890"
})

print("Status: " .. result.status)
print("Amount: " .. result.transaction_amount)
print("Payer: " .. result.payer.email)

create_payment

Create a new payment in Mercado Pago.

Parameters

NameTypeRequiredDescription
transaction_amountnumberyesAmount to charge (e.g., 100.50)
payment_method_idstringyesPayment method (e.g., "visa", "master", "pix", "boleto")
payer_emailstringyesPayer’s email address
installmentsintegernoNumber of installments (default: 1)

Common Payment Method IDs

IDDescription
visaVisa credit/debit
masterMastercard
amexAmerican Express
pixPix (Brazil instant payment)
boletoBoleto (Brazilian payment slip)

Example

local result = app.integrations["mercado-pago"].create_payment({
  transaction_amount = 150.00,
  payment_method_id = "visa",
  payer_email = "[email protected]",
  installments = 3
})

print("Payment ID: " .. result.id)
print("Status: " .. result.status)

list_customers

Search and list customers.

Parameters

NameTypeRequiredDescription
emailstringnoFilter by customer email
limitintegernoMax results (default: 30)
offsetintegernoNumber of results to skip (default: 0)

Example

local result = app.integrations["mercado-pago"].list_customers({
  email = "[email protected]"
})

for _, customer in ipairs(result.results) do
  print(customer.id .. ": " .. customer.email)
end

get_customer

Retrieve details of a specific customer.

Parameters

NameTypeRequiredDescription
idstringyesMercado Pago customer ID

Example

local result = app.integrations["mercado-pago"].get_customer({
  id = "123456789-abcdefghijkl"
})

print("Name: " .. result.first_name .. " " .. result.last_name)
print("Email: " .. result.email)

list_preferences

List checkout preferences.

Parameters

NameTypeRequiredDescription
limitintegernoMax results (default: 30)
offsetintegernoNumber of results to skip (default: 0)
sponsor_idstringnoFilter by sponsor user ID

Example

local result = app.integrations["mercado-pago"].list_preferences({
  limit = 10
})

for _, pref in ipairs(result.elements) do
  print(pref.id .. ": " .. pref.items[1].title)
end

get_current_user

Get the authenticated user’s account information. No parameters required.

Example

local result = app.integrations["mercado-pago"].get_current_user({})

print("User: " .. result.first_name .. " " .. result.last_name)
print("Email: " .. result.email)
print("ID: " .. result.id)

Multi-Account Usage

If you have multiple Mercado Pago accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations["mercado-pago"].list_payments({...})

-- Explicit default (portable across setups)
app.integrations["mercado-pago"].default.list_payments({...})

-- Named accounts
app.integrations["mercado-pago"].brazil.list_payments({...})
app.integrations["mercado-pago"].argentina.list_payments({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Mercado Pago — Lua API Reference

## list_payments

Search and list payments from Mercado Pago with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Max results (default: 30, max: 1000) |
| `offset` | integer | no | Number of results to skip (default: 0) |
| `external_reference` | string | no | Filter by your custom external reference |
| `status` | string | no | Payment status filter (see values below) |
| `date_created_from` | string | no | Created after (ISO 8601, e.g., `"2025-01-01T00:00:00.000-00:00"`) |
| `date_created_to` | string | no | Created before (ISO 8601, e.g., `"2025-12-31T23:59:59.999-00:00"`) |

### Payment Status Values

`pending`, `approved`, `authorized`, `in_process`, `in_mediation`, `rejected`, `cancelled`, `refunded`, `charged_back`

### Example

```lua
local result = app.integrations["mercado-pago"].list_payments({
  status = "approved",
  limit = 10
})

for _, payment in ipairs(result.results) do
  print(payment.id .. ": " .. payment.transaction_amount .. " " .. payment.currency_id)
end
```

---

## get_payment

Retrieve full details of a specific payment.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Mercado Pago payment ID |

### Example

```lua
local result = app.integrations["mercado-pago"].get_payment({
  id = "1234567890"
})

print("Status: " .. result.status)
print("Amount: " .. result.transaction_amount)
print("Payer: " .. result.payer.email)
```

---

## create_payment

Create a new payment in Mercado Pago.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `transaction_amount` | number | yes | Amount to charge (e.g., `100.50`) |
| `payment_method_id` | string | yes | Payment method (e.g., `"visa"`, `"master"`, `"pix"`, `"boleto"`) |
| `payer_email` | string | yes | Payer's email address |
| `installments` | integer | no | Number of installments (default: 1) |

### Common Payment Method IDs

| ID | Description |
|----|-------------|
| `visa` | Visa credit/debit |
| `master` | Mastercard |
| `amex` | American Express |
| `pix` | Pix (Brazil instant payment) |
| `boleto` | Boleto (Brazilian payment slip) |

### Example

```lua
local result = app.integrations["mercado-pago"].create_payment({
  transaction_amount = 150.00,
  payment_method_id = "visa",
  payer_email = "[email protected]",
  installments = 3
})

print("Payment ID: " .. result.id)
print("Status: " .. result.status)
```

---

## list_customers

Search and list customers.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | no | Filter by customer email |
| `limit` | integer | no | Max results (default: 30) |
| `offset` | integer | no | Number of results to skip (default: 0) |

### Example

```lua
local result = app.integrations["mercado-pago"].list_customers({
  email = "[email protected]"
})

for _, customer in ipairs(result.results) do
  print(customer.id .. ": " .. customer.email)
end
```

---

## get_customer

Retrieve details of a specific customer.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Mercado Pago customer ID |

### Example

```lua
local result = app.integrations["mercado-pago"].get_customer({
  id = "123456789-abcdefghijkl"
})

print("Name: " .. result.first_name .. " " .. result.last_name)
print("Email: " .. result.email)
```

---

## list_preferences

List checkout preferences.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Max results (default: 30) |
| `offset` | integer | no | Number of results to skip (default: 0) |
| `sponsor_id` | string | no | Filter by sponsor user ID |

### Example

```lua
local result = app.integrations["mercado-pago"].list_preferences({
  limit = 10
})

for _, pref in ipairs(result.elements) do
  print(pref.id .. ": " .. pref.items[1].title)
end
```

---

## get_current_user

Get the authenticated user's account information. No parameters required.

### Example

```lua
local result = app.integrations["mercado-pago"].get_current_user({})

print("User: " .. result.first_name .. " " .. result.last_name)
print("Email: " .. result.email)
print("ID: " .. result.id)
```

---

## Multi-Account Usage

If you have multiple Mercado Pago accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations["mercado-pago"].list_payments({...})

-- Explicit default (portable across setups)
app.integrations["mercado-pago"].default.list_payments({...})

-- Named accounts
app.integrations["mercado-pago"].brazil.list_payments({...})
app.integrations["mercado-pago"].argentina.list_payments({...})
```

All functions are identical across accounts — only the credentials differ.

Metadata-Derived Lua Example

local result = app.integrations.mercado_pago.mercado_pago_list_payments({
  limit = 1,
  offset = 1,
  external_reference = "example_external_reference",
  status = "example_status",
  date_created_from = "example_date_created_from",
  date_created_to = "example_date_created_to"
})
print(result)

Functions

mercado_pago_list_payments

Search and list payments from Mercado Pago. Supports filtering by status, external reference, and date range. Returns a paginated list of payment records.

Operation
Read read
Full name
mercado-pago.mercado_pago_list_payments
ParameterTypeRequiredDescription
limit integer no Maximum number of results to return (default: 30, max: 1000).
offset integer no Number of results to skip for pagination (default: 0).
external_reference string no Filter by the external reference you set when creating the payment.
status string no Filter by payment status: pending, approved, authorized, in_process, in_mediation, rejected, cancelled, refunded, charged_back.
date_created_from string no Filter payments created after this date (ISO 8601, e.g., "2025-01-01T00:00:00.000-00:00").
date_created_to string no Filter payments created before this date (ISO 8601, e.g., "2025-12-31T23:59:59.999-00:00").

mercado_pago_get_payment

Retrieve full details of a specific Mercado Pago payment by its ID. Returns payment status, amount, payer information, and more.

Operation
Read read
Full name
mercado-pago.mercado_pago_get_payment
ParameterTypeRequiredDescription
id string yes The Mercado Pago payment ID.

mercado_pago_create_payment

Create a new payment in Mercado Pago. Requires the transaction amount, payment method ID, and payer email. Optionally specify the number of installments.

Operation
Write write
Full name
mercado-pago.mercado_pago_create_payment
ParameterTypeRequiredDescription
transaction_amount number yes The amount to charge (positive number, e.g., 100.50).
payment_method_id string yes The payment method ID (e.g., "visa", "master", "pix", "boleto", "amex").
payer_email string yes The payer's email address.
installments integer no Number of installments for credit card payments (default: 1).

mercado_pago_list_customers

Search and list customers in Mercado Pago. Optionally filter by email. Returns a paginated list of customer records.

Operation
Read read
Full name
mercado-pago.mercado_pago_list_customers
ParameterTypeRequiredDescription
email string no Filter customers by email address.
limit integer no Maximum number of results to return (default: 30).
offset integer no Number of results to skip for pagination (default: 0).

mercado_pago_get_customer

Retrieve full details of a specific Mercado Pago customer by their ID. Returns customer name, email, default card, and more.

Operation
Read read
Full name
mercado-pago.mercado_pago_get_customer
ParameterTypeRequiredDescription
id string yes The Mercado Pago customer ID.

mercado_pago_list_preferences

List checkout preferences from Mercado Pago. Returns a paginated list of checkout preference objects that define items, payer details, and payment settings.

Operation
Read read
Full name
mercado-pago.mercado_pago_list_preferences
ParameterTypeRequiredDescription
limit integer no Maximum number of results to return (default: 30).
offset integer no Number of results to skip for pagination (default: 0).
sponsor_id string no Filter preferences by the sponsor user ID.

mercado_pago_get_current_user

Get the authenticated Mercado Pago user's account information, including name, email, and user ID.

Operation
Read read
Full name
mercado-pago.mercado_pago_get_current_user
ParameterTypeRequiredDescription
No parameters.