KosmoKrator

finance

Paystack Lua API for KosmoKrator Agents

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

7 functions 5 read 2 write API key auth
Submit Paystack feedback View package source

Lua Namespace

Agents call this integration through app.integrations.paystack.*. Use lua_read_doc("integrations.paystack") 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.

Paystack — Lua API Reference

list_transactions

List transactions on your Paystack integration.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of transactions per page (default: 50, max: 100)
pageintegernoPage number to retrieve
statusstringnoFilter by status: "success", "failed", "abandoned", "reversed"
customerstringnoFilter by customer ID or email
fromstringnoStart date (ISO 8601, e.g., "2025-01-01T00:00:00")
tostringnoEnd date (ISO 8601, e.g., "2025-01-31T23:59:59")

Example

local result = app.integrations.paystack.list_transactions({
  per_page = 10,
  status = "success"
})

for _, tx in ipairs(result.data) do
  print(tx.id .. ": " .. tx.amount .. " (" .. tx.status .. ")")
end

get_transaction

Get details of a specific transaction.

Parameters

NameTypeRequiredDescription
idstringyesTransaction ID or reference

Example

local result = app.integrations.paystack.get_transaction({
  id = "123456789"
})

print("Status: " .. result.data.status)
print("Amount: " .. result.data.amount)

initialize_transaction

Initialize a new payment transaction. Returns an authorization URL for the customer.

Parameters

NameTypeRequiredDescription
amountintegeryesAmount in kobo (e.g., 50000 for ₦500.00)
emailstringyesCustomer email address
referencestringnoUnique transaction reference
callback_urlstringnoURL to redirect after payment

Example

local result = app.integrations.paystack.initialize_transaction({
  amount = 50000,
  email = "[email protected]",
  callback_url = "https://example.com/callback"
})

print("Authorization URL: " .. result.data.authorization_url)
print("Reference: " .. result.data.reference)

list_customers

List customers on your integration.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of customers per page (default: 50)
pageintegernoPage number to retrieve

Example

local result = app.integrations.paystack.list_customers({
  per_page = 20
})

for _, cust in ipairs(result.data) do
  print(cust.email .. " - " .. (cust.first_name or "") .. " " .. (cust.last_name or ""))
end

create_customer

Create a new customer.

Parameters

NameTypeRequiredDescription
emailstringyesCustomer email address
first_namestringnoCustomer first name
last_namestringnoCustomer last name
phonestringnoCustomer phone number

Example

local result = app.integrations.paystack.create_customer({
  email = "[email protected]",
  first_name = "Jane",
  last_name = "Doe",
  phone = "+2348012345678"
})

print("Created customer: " .. result.data.email)

list_plans

List subscription plans.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of plans per page (default: 50)
pageintegernoPage number to retrieve
statusstringnoFilter by status: "active" or "inactive"

Example

local result = app.integrations.paystack.list_plans({
  status = "active"
})

for _, plan in ipairs(result.data) do
  print(plan.name .. " - " .. plan.amount .. " kobo / " .. plan.interval)
end

get_current_user

Verify the Paystack API connection and retrieve payment session timeout settings.

Parameters

None.

Example

local result = app.integrations.paystack.get_current_user({})

print("Payment session timeout: " .. result.data.payment_session_timeout)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.paystack.list_transactions({})

-- Explicit default (portable across setups)
app.integrations.paystack.default.list_transactions({})

-- Named accounts
app.integrations.paystack.production.list_transactions({})
app.integrations.paystack.test.list_transactions({})

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

Raw agent markdown 
# Paystack — Lua API Reference

## list_transactions

List transactions on your Paystack integration.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of transactions per page (default: 50, max: 100) |
| `page` | integer | no | Page number to retrieve |
| `status` | string | no | Filter by status: `"success"`, `"failed"`, `"abandoned"`, `"reversed"` |
| `customer` | string | no | Filter by customer ID or email |
| `from` | string | no | Start date (ISO 8601, e.g., `"2025-01-01T00:00:00"`) |
| `to` | string | no | End date (ISO 8601, e.g., `"2025-01-31T23:59:59"`) |

### Example

```lua
local result = app.integrations.paystack.list_transactions({
  per_page = 10,
  status = "success"
})

for _, tx in ipairs(result.data) do
  print(tx.id .. ": " .. tx.amount .. " (" .. tx.status .. ")")
end
```

---

## get_transaction

Get details of a specific transaction.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Transaction ID or reference |

### Example

```lua
local result = app.integrations.paystack.get_transaction({
  id = "123456789"
})

print("Status: " .. result.data.status)
print("Amount: " .. result.data.amount)
```

---

## initialize_transaction

Initialize a new payment transaction. Returns an authorization URL for the customer.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `amount` | integer | yes | Amount in kobo (e.g., `50000` for ₦500.00) |
| `email` | string | yes | Customer email address |
| `reference` | string | no | Unique transaction reference |
| `callback_url` | string | no | URL to redirect after payment |

### Example

```lua
local result = app.integrations.paystack.initialize_transaction({
  amount = 50000,
  email = "[email protected]",
  callback_url = "https://example.com/callback"
})

print("Authorization URL: " .. result.data.authorization_url)
print("Reference: " .. result.data.reference)
```

---

## list_customers

List customers on your integration.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of customers per page (default: 50) |
| `page` | integer | no | Page number to retrieve |

### Example

```lua
local result = app.integrations.paystack.list_customers({
  per_page = 20
})

for _, cust in ipairs(result.data) do
  print(cust.email .. " - " .. (cust.first_name or "") .. " " .. (cust.last_name or ""))
end
```

---

## create_customer

Create a new customer.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | yes | Customer email address |
| `first_name` | string | no | Customer first name |
| `last_name` | string | no | Customer last name |
| `phone` | string | no | Customer phone number |

### Example

```lua
local result = app.integrations.paystack.create_customer({
  email = "[email protected]",
  first_name = "Jane",
  last_name = "Doe",
  phone = "+2348012345678"
})

print("Created customer: " .. result.data.email)
```

---

## list_plans

List subscription plans.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of plans per page (default: 50) |
| `page` | integer | no | Page number to retrieve |
| `status` | string | no | Filter by status: `"active"` or `"inactive"` |

### Example

```lua
local result = app.integrations.paystack.list_plans({
  status = "active"
})

for _, plan in ipairs(result.data) do
  print(plan.name .. " - " .. plan.amount .. " kobo / " .. plan.interval)
end
```

---

## get_current_user

Verify the Paystack API connection and retrieve payment session timeout settings.

### Parameters

None.

### Example

```lua
local result = app.integrations.paystack.get_current_user({})

print("Payment session timeout: " .. result.data.payment_session_timeout)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.paystack.list_transactions({})

-- Explicit default (portable across setups)
app.integrations.paystack.default.list_transactions({})

-- Named accounts
app.integrations.paystack.production.list_transactions({})
app.integrations.paystack.test.list_transactions({})
```

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

Metadata-Derived Lua Example

local result = app.integrations.paystack.paystack_list_transactions({
  per_page = 1,
  page = 1,
  status = "example_status",
  customer = "example_customer",
  from = "example_from",
  to = "example_to"
})
print(result)

Functions

paystack_list_transactions

List transactions on your Paystack integration. Supports filtering by status, customer, and date range with pagination.

Operation
Read read
Full name
paystack.paystack_list_transactions
ParameterTypeRequiredDescription
per_page integer no Number of transactions per page (default: 50, max: 100).
page integer no Page number to retrieve.
status string no Filter by status: "success", "failed", "abandoned", "reversed".
customer string no Filter by customer ID or email.
from string no Start date for filtering (ISO 8601, e.g., "2025-01-01T00:00:00").
to string no End date for filtering (ISO 8601, e.g., "2025-01-31T23:59:59").

paystack_get_transaction

Get details of a specific Paystack transaction by its ID or reference.

Operation
Read read
Full name
paystack.paystack_get_transaction
ParameterTypeRequiredDescription
id string yes Transaction ID or reference.

paystack_initialize_transaction

Initialize a new payment transaction on Paystack. Returns an authorization URL for the customer to complete payment.

Operation
Write write
Full name
paystack.paystack_initialize_transaction
ParameterTypeRequiredDescription
amount integer yes Amount in kobo (e.g., 50000 for ₦500.00).
email string yes Customer email address.
reference string no Unique transaction reference. If not provided, Paystack generates one.
callback_url string no URL to redirect customer to after payment.

paystack_list_customers

List customers on your Paystack integration. Supports pagination.

Operation
Read read
Full name
paystack.paystack_list_customers
ParameterTypeRequiredDescription
per_page integer no Number of customers per page (default: 50, max: 100).
page integer no Page number to retrieve.

paystack_create_customer

Create a new customer on your Paystack integration.

Operation
Write write
Full name
paystack.paystack_create_customer
ParameterTypeRequiredDescription
email string yes Customer email address.
first_name string no Customer first name.
last_name string no Customer last name.
phone string no Customer phone number.

paystack_list_plans

List subscription plans on your Paystack integration. Supports filtering by status and pagination.

Operation
Read read
Full name
paystack.paystack_list_plans
ParameterTypeRequiredDescription
per_page integer no Number of plans per page (default: 50, max: 100).
page integer no Page number to retrieve.
status string no Filter by status: "active" or "inactive".

paystack_get_current_user

Verify the Paystack API connection and retrieve integration payment session timeout settings. Use this to check if the API key is valid and the service is reachable.

Operation
Read read
Full name
paystack.paystack_get_current_user
ParameterTypeRequiredDescription
No parameters.