ToyyibPay

🔑 BYO Key — Payments

Malaysian payment gateway for FPX online banking, cards and DuitNow QR. Create bills and confirm their payment status server-side. Sandbox endpoints (*-sandbox) are included for testing.

🔑 Setup Required — Bring Your Own Key This integration requires API credentials. Store them once via setup_integration or the Dashboard Vault — they're encrypted with AES-256-GCM and never exposed.

Required Credentials

toyyibpay_user_secret

User Secret Key

Your production User Secret Key from the toyyibpay.com dashboard.

Get your API key at toyyibpay.com →

Endpoints (8)

POST create-category

Create a bill category. Every bill belongs to a category; usually one is enough per site. Returns the CategoryCode.

Field	Type	Required	Description
`name`	string	✓ Yes	Category name.
`description`	string	✓ Yes	Category description.

POST get-category

Get the details of a bill category.

Field	Type	Required	Description
`category_code`	string	✓ Yes	CategoryCode returned by create-category.

POST create-bill

Create a fixed-amount bill. Returns a BillCode; send the customer to https://toyyibpay.com/{BillCode}. Always confirm payment with get-bill-transactions before fulfilling — never trust the return URL alone.

Field	Type	Required	Description
`category_code`	string	✓ Yes	CategoryCode returned by create-category.
`name`	string	✓ Yes	Bill name, max 30 characters: letters, digits, spaces and underscores only.
`description`	string	✓ Yes	Bill description, max 100 characters.
`amount_cents`	integer	✓ Yes	Amount in sen (cents), e.g. 2500 for RM 25.00. Minimum RM 1.00.
`payment_channel`	integer	✓ Yes	0 = FPX online banking, 1 = card, 2 = both.
`return_url`	url	✓ Yes	Where the customer lands after paying. Show a "checking payment" page there and confirm with get-bill-transactions.
`callback_url`	url	✓ Yes	Server-to-server notification URL. Note: WebsitePublisher does not verify ToyyibPay callbacks yet — confirm payment with get-bill-transactions.
`reference`	string	✓ Yes	Your own order reference (sent as billExternalReferenceNo).
`payer_name`	string	✓ Yes	Customer name.
`payer_email`	email	✓ Yes	Customer email address.
`payer_phone`	string	✓ Yes	Customer phone number, e.g. 0123456789.

POST get-bill-transactions

Get the payment attempts of a bill. billpaymentStatus "1" means paid. Use this server-side to confirm a payment before marking an order paid.

Field	Type	Required	Description
`bill_code`	string	✓ Yes	BillCode returned by create-bill.

POST create-category-sandbox

Create a bill category. Every bill belongs to a category; usually one is enough per site. Returns the CategoryCode. (sandbox — test payments only, needs vault key toyyibpay_sandbox_user_secret)

Field	Type	Required	Description
`name`	string	✓ Yes	Category name.
`description`	string	✓ Yes	Category description.

POST get-category-sandbox

Get the details of a bill category. (sandbox — test payments only, needs vault key toyyibpay_sandbox_user_secret)

Field	Type	Required	Description
`category_code`	string	✓ Yes	CategoryCode returned by create-category.

POST create-bill-sandbox

Create a fixed-amount bill. Returns a BillCode; send the customer to https://dev.toyyibpay.com/{BillCode}. Always confirm payment with get-bill-transactions-sandbox before fulfilling — never trust the return URL alone. (sandbox — test payments only, needs vault key toyyibpay_sandbox_user_secret)

Field	Type	Required	Description
`category_code`	string	✓ Yes	CategoryCode returned by create-category.
`name`	string	✓ Yes	Bill name, max 30 characters: letters, digits, spaces and underscores only.
`description`	string	✓ Yes	Bill description, max 100 characters.
`amount_cents`	integer	✓ Yes	Amount in sen (cents), e.g. 2500 for RM 25.00. Minimum RM 1.00.
`payment_channel`	integer	✓ Yes	0 = FPX online banking, 1 = card, 2 = both.
`return_url`	url	✓ Yes	Where the customer lands after paying. Show a "checking payment" page there and confirm with get-bill-transactions.
`callback_url`	url	✓ Yes	Server-to-server notification URL. Note: WebsitePublisher does not verify ToyyibPay callbacks yet — confirm payment with get-bill-transactions.
`reference`	string	✓ Yes	Your own order reference (sent as billExternalReferenceNo).
`payer_name`	string	✓ Yes	Customer name.
`payer_email`	email	✓ Yes	Customer email address.
`payer_phone`	string	✓ Yes	Customer phone number, e.g. 0123456789.

POST get-bill-transactions-sandbox

Get the payment attempts of a bill. billpaymentStatus "1" means paid. Use this server-side to confirm a payment before marking an order paid. (sandbox — test payments only, needs vault key toyyibpay_sandbox_user_secret)

Field	Type	Required	Description
`bill_code`	string	✓ Yes	BillCode returned by create-bill.

MCP Tool Names

When using this integration through an AI assistant (Claude, ChatGPT, Cursor, etc.), the endpoints are available as MCP tools:

Endpoint	MCP Tool Name
create-category	`toyyibpay_create_category`
get-category	`toyyibpay_get_category`
create-bill	`toyyibpay_create_bill`
get-bill-transactions	`toyyibpay_get_bill_transactions`
create-category-sandbox	`toyyibpay_create_category_sandbox`
get-category-sandbox	`toyyibpay_get_category_sandbox`
create-bill-sandbox	`toyyibpay_create_bill_sandbox`
get-bill-transactions-sandbox	`toyyibpay_get_bill_transactions_sandbox`

← Back to all integrations