Skip to content
Better Payment

Plugins

Add features to Better Payment with plugins — payment events, provider routing and your own logic.

Added in 0.5.0

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

PartWhat it doesExample
eventsListens to payment eventsUpdate orders, send e-mails, keep an audit log
hooks.beforeRuns before an operation. It can choose the provider, change the request, or return a result without calling the providerSend payments to the cheapest provider, block a card, add an order id
hooks.afterRuns after an operation and can replace its resultTranslate error messages
initRuns once, before the first operationLoad rate tables, warm up a cache
methodsAdds members to the payment objectpayment.router.quote()
endpointsAdds routes to the HTTP handlerPOST /api/pay/router/quote
$ERROR_CODESDeclares the plugin's error codesNO_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:

PluginWhat it does
i18nError messages for customers, in their language (English, Turkish, German, Russian, and Arabic included)
chaosInjects failures and delays into operations, to test how your application handles them
notificationsSends sales, refunds and failures to Slack, Discord, Telegram or your own channel
openAPIOpenAPI 3.1.0 schema generation and interactive Scalar reference documentation for handler endpoints
failoverRetries payments on backup providers when a provider is down, with a circuit breaker
currencyConversionConverts amounts with TCMB exchange rates, with markup, kuruş-accurate baskets and refund rate locking
redactMasks card data, CVV and personal data in logs, events and audit trails
threeDSTimeoutTracks started 3D Secure payments and expires abandoned ones
captchaVerifies a Turnstile, reCAPTCHA or hCaptcha token before payment operations
rateLimitThrottles incoming HTTP handler requests to protect against bot floods and card testing
pendingResolverQueries and resolves timed out payments (NETWORK_ERROR) on a schedule
refundApprovalRequires manager review and approval for refunds and cancellations above a threshold
webhookForwardingForwards payment events to external microservices as HMAC-SHA256 signed webhooks with retries
mcpExposes Better Payment as a Model Context Protocol (MCP) server for AI agents
telemetryOpenTelemetry-compatible spans and metrics for every provider call, with no card data in attributes
fraudRulesCounts attempts per IP, card and buyer and refuses card-testing runs before the provider is called (subpath better-payment/fraud)
commissionRouterRoutes each payment to the cheapest eligible provider from your own commission rate tables (subpath better-payment/commission-router)
routingPicks 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.