Coming v0.1.0

Tools reference

All ten tools, their inputs and constraints, HITL behaviour, and rate limits. Full Zod schemas live in the tracent-paystack-mcp repository; this page is the customer-facing surface.

~8 min read

Global rate limits

On top of the per-tool limits below, the gateway-core enforces a global ceiling per user across the whole Paystack server: 60/min, 1,000/hour, 10,000/day. Hits return a structured error with isError: true and a retry-after suggestion.

create_payment_link

Create a payment link

HITL conditional

Initialise a transaction and return an authorised payment URL.

Paystack endpoint:: POST /transaction/initialize
Rate limit:: 30/min · 500/hour
PII redaction:: Yes (response scrubbed)
HITL note:: Gated when amount > ₦100,000 (10,000,000 kobo).

Inputs

Name	Type	Required	Notes
`amountKobo`	`integer`	Yes	100 to 50,000,000
`email`	`string`	Yes	Valid email, max 255 chars
`currency`	`enum`	No	NGN \| USD \| GHS \| ZAR \| KES, default NGN
`reference`	`string`	No	Pattern [a-zA-Z0-9_-]{1,32}
`metadata`	`record<string,string>`	No	Each value max 200 chars

Example prompt

“Generate a payment link for Mary's outstanding ₦25,000 invoice.”

Pidgin: “Make payment link for Mary outstanding ₦25,000 invoice.”

verify_payment

Verify a payment

Confirm the status of a transaction by its reference.

Paystack endpoint:: GET /transaction/verify/:reference
Rate limit:: 120/min · 2,000/hour
PII redaction:: Yes (response scrubbed)

Inputs

Name	Type	Required	Notes
`reference`	`string`	Yes	The transaction reference returned at creation.

Example prompt

“Did the payment for reference INV-2026-001 settle?”

list_transactions

List transactions

Paginated transactions with status, amount, and date filters.

Paystack endpoint:: GET /transaction
Rate limit:: 60/min · 1,000/hour
PII redaction:: Yes (response scrubbed)

Inputs

Name	Type	Required	Notes
`perPage`	`integer`	No	1-100, default 50
`page`	`integer`	No	Default 1
`status`	`enum`	No	success \| failed \| pending \| abandoned
`from`	`date`	No	ISO 8601
`to`	`date`	No	ISO 8601
`amountMinKobo`	`integer`	No	-
`amountMaxKobo`	`integer`	No	-

Example prompt

“Show me yesterday's failed transactions over ₦100,000.”

Pidgin: “Show me yesterday transactions wey fail and pass ₦100,000.”

get_transaction

Get a transaction

Full detail for a single transaction.

Paystack endpoint:: GET /transaction/:id
Rate limit:: 120/min · 2,000/hour
PII redaction:: Yes (response scrubbed)

Inputs

Name	Type	Required	Notes
`id`	`integer`	No	Paystack transaction id; one of id or reference required
`reference`	`string`	No	Transaction reference

Example prompt

“Pull the full record for transaction 4892173.”

list_customers

List customers

Paginated customers with email and phone tokenised.

Paystack endpoint:: GET /customer
Rate limit:: 60/min · 1,000/hour
PII redaction:: Yes (response scrubbed)

Inputs

Name	Type	Required	Notes
`perPage`	`integer`	No	1-100, default 50
`page`	`integer`	No	-

Example prompt

“List the most recent twenty customers.”

create_customer

Create a customer

HITL always

Paystack endpoint:: POST /customer
Rate limit:: 20/min · 300/hour
PII redaction:: Yes (response scrubbed)
HITL note:: Every customer creation requires PIN approval.

Inputs

Name	Type	Required	Notes
`email`	`string`	Yes	Valid email
`firstName`	`string`	Yes	Max 100 chars
`lastName`	`string`	Yes	Max 100 chars
`phone`	`string`	No	E.164 pattern

Example prompt

“Add Bashir Yusuf as a customer with email bashir@example.com.”

initiate_refund

Initiate a refund

HITL always

Refund a transaction, fully or partially.

Paystack endpoint:: POST /refund
Rate limit:: 5/min · 50/hour
PII redaction:: Yes (response scrubbed)
HITL note:: Always PIN-gated. Amount defaults to full transaction.

Inputs

Name	Type	Required	Notes
`transactionReference`	`string`	Yes	-
`amountKobo`	`integer`	No	Defaults to full transaction
`customerNote`	`string`	No	Max 500 chars

Example prompt

“Refund the duplicate payment on INV-2026-0042.”

list_balances

List balances

Current balances per currency, in kobo.

Paystack endpoint:: GET /balance
Rate limit:: 30/min · 500/hour
PII redaction:: No (no PII)

No inputs. Call the tool with an empty argument object.

Example prompt

“What's our NGN balance right now?”

Pidgin: “Wetin be our NGN balance now?”

get_settlements

List settlements

Settlement history with amounts and dates.

Paystack endpoint:: GET /settlement
Rate limit:: 30/min · 500/hour
PII redaction:: No (no PII)

Inputs

Name	Type	Required	Notes
`perPage`	`integer`	No	-
`page`	`integer`	No	-
`from`	`date`	No	-
`to`	`date`	No	-

Example prompt

“Reconcile this week's settlements.”

list_payment_pages

List payment pages

Recurring payment pages with slugs and URLs.

Paystack endpoint:: GET /page
Rate limit:: 30/min · 500/hour
PII redaction:: No (no PII)

Inputs

Name	Type	Required	Notes
`perPage`	`integer`	No	-
`page`	`integer`	No	-

Example prompt

“Show all active subscription payment pages.”