Plugins
Add features to Better Payment with plugins — payment events, provider routing and your own logic.
A plugin adds behaviour to the payment object without changing the library. It can react to payment events, run code before and after provider operations, add methods to the payment object and routes to the HTTP handler. Plugins are plain objects, so a plugin often fits in a few lines, and you can write your own.
Using plugins
import { betterPayment, iyzico, paytr } from 'better-payment';
import { auditLog } from './plugins/audit-log';
export const payment = betterPayment({
providers: {
iyzico: iyzico({ /* ... */ }),
paytr: paytr({ /* ... */ }),
},
plugins: [auditLog()],
});Plugins run in the order of the plugins array. Their hooks, event listeners and endpoints are registered when the payment object is created. Their init runs once, before the first operation.
What a plugin can do
| Part | What it does | Example |
|---|---|---|
events | Listens to payment events | Update orders, send e-mails, keep an audit log |
hooks.before | Runs before an operation. It can choose the provider, change the request, or return a result without calling the provider | Send payments to the cheapest provider, block a card, add an order id |
hooks.after | Runs after an operation and can replace its result | Translate error messages |
init | Runs once, before the first operation | Load rate tables, warm up a cache |
methods | Adds members to the payment object | payment.router.quote() |
endpoints | Adds routes to the HTTP handler | POST /api/pay/router/quote |
$ERROR_CODES | Declares the plugin's error codes | NO_ELIGIBLE_PROVIDER |
Everything a plugin adds is typed: payment.router.quote() autocompletes, and a typo is a type error.
Operations
Hooks run for these operations, whether they are called on the payment object (payment.createPayment()), on a provider (payment.iyzico.createPayment()) or through the HTTP handler:
createPayment, initThreeDSPayment, completeThreeDSPayment, authorize, initThreeDSAuthorize, capture, voidAuthorization, refund, cancel, getPayment, saveCard, listCards, deleteCard, binCheck, installmentInfo
Provider-specific methods (the iyzico checkout form, PWI and subscriptions, PayTR token payments) run without hooks.
A hook can move only calls made on the payment object to another provider. A call made on a provider (payment.iyzico.refund()), or through a provider route of the handler, always runs on that provider: refunds, cancels and status queries must reach the provider that took the payment.
Official plugins
Official plugins ship in the package: most under better-payment/plugins, and larger ones under their own subpath:
| Plugin | What it does |
|---|---|
i18n | Error messages for customers, in their language (English, Turkish, German, Russian, and Arabic included) |
chaos | Injects failures and delays into operations, to test how your application handles them |
notifications | Sends sales, refunds and failures to Slack, Discord, Telegram or your own channel |
openAPI | OpenAPI 3.1.0 schema generation and interactive Scalar reference documentation for handler endpoints |
failover | Retries payments on backup providers when a provider is down, with a circuit breaker |
currencyConversion | Converts amounts with TCMB exchange rates, with markup, kuruş-accurate baskets and refund rate locking |
redact | Masks card data, CVV and personal data in logs, events and audit trails |
threeDSTimeout | Tracks started 3D Secure payments and expires abandoned ones |
captcha | Verifies a Turnstile, reCAPTCHA or hCaptcha token before payment operations |
rateLimit | Throttles incoming HTTP handler requests to protect against bot floods and card testing |
pendingResolver | Queries and resolves timed out payments (NETWORK_ERROR) on a schedule |
refundApproval | Requires manager review and approval for refunds and cancellations above a threshold |
webhookForwarding | Forwards payment events to external microservices as HMAC-SHA256 signed webhooks with retries |
mcp | Exposes Better Payment as a Model Context Protocol (MCP) server for AI agents |
telemetry | OpenTelemetry-compatible spans and metrics for every provider call, with no card data in attributes |
fraudRules | Counts attempts per IP, card and buyer and refuses card-testing runs before the provider is called (subpath better-payment/fraud) |
commissionRouter | Routes each payment to the cheapest eligible provider from your own commission rate tables (subpath better-payment/commission-router) |
routing | Picks the provider of each payment by card family, card origin, amount, installment and health (subpath better-payment/routing) |
Need something else? Write your own; it takes a few lines.