Payment

iyzico & Stripe with 3-D Secure

The payment block adds checkout to your API without committing you to one processor. A provider abstraction sits in front of iyzico and Stripe, so the same routes, saved-card flows and webhook handling work whichever you choose.

It covers the full lifecycle: redirect-based checkout, 3-D Secure, saved payment methods, marketplace sub-merchant splitting, and a provider callback for asynchronous results. Provider credentials are referenced by env-var name and never inlined.

Provider & flow#

Select the processor and define where users land after a payment resolves. Redirect URLs drive the hosted-checkout return journey.

enabledbooleanOptional

Mount the payment routes and initialise the chosen provider.

Defaultfalse

provider'iyzico' | 'stripe'Optional

The active payment processor. Fill in the matching credentials block below.

basePathstringOptional

Route prefix for all payment endpoints.

Default"/payment"

defaultCurrency / defaultLocalestringOptional

Fallback currency (e.g. TRY, USD, EUR) and locale (e.g. tr, en) when a request omits them.

successRedirectUrl / failedRedirectUrl / errorRedirectUrlstringOptional

Where the browser is sent after a successful, failed or errored payment respectively.

callbackUrlstringOptional

URL the provider posts asynchronous results back to. Auto-generated from basePath if omitted.

Capabilities#

Opt into the richer payment features. 3-D Secure is strongly recommended; saved methods and sub-merchants unlock returning-customer and marketplace scenarios.

savedMethodsEnabledbooleanOptional

Let users store cards for faster repeat checkout (provider-tokenised; no PAN touches your DB).

threeDSecureEnabledbooleanOptional

Enable the 3-D Secure challenge flow. Recommended — shifts liability and satisfies SCA requirements.

subMerchantsEnabledbooleanOptional

Enable marketplace sub-merchants so a payment can be split and commission retained.

iyzico#

Credentials for the iyzico processor. Each field accepts a literal value or — preferably — the name of an env var holding the secret.

iyzicoobjectOptional

iyzico provider credentials.

apiUrlstringOptional

iyzico API base URL (env-var name or literal). Use the sandbox URL in development.

apiKeystringOptional

iyzico API key (env-var name or literal). Sensitive.

secretKeystringOptional

iyzico secret key (env-var name or literal). Sensitive.

Stripe#

Credentials and client tuning for Stripe. Requires the optional stripe npm package. The webhook secret verifies that incoming events genuinely came from Stripe.

stripeobjectOptional

Stripe provider configuration.

secretKeystringOptional

Stripe secret key (sk_test_… / sk_live_…), as env-var name or literal. Sensitive.

webhookSecretstringOptional

Webhook signing secret (whsec_…) used to verify event authenticity. Sensitive.

apiVersionstringOptional

Pin a Stripe API version. Defaults to the library's latest.

maxNetworkRetriesnumberOptional

Automatic retry count for transient network failures.

Default2

timeoutnumberOptional

Per-request timeout in milliseconds.

Default30000

Under the hood — provider abstraction#

createPaymentService reads your config and returns a single PaymentProvider, so the routes never know which gateway they're talking to. It fails safe: a missing or half-configured provider returns null and the payment routes simply don't mount.

one interface, two providersPaymentProviderOptional

iyzico and stripe each implement the same PaymentProvider contract (createIyzicoProvider / createStripeProvider). Your code and the generated routes call the interface; swapping providers is a config change, not a code change.

env-resolved credentialsresolveEnvValueOptional

Every credential (apiKey, secretKey, webhookSecret, apiUrl) is run through resolveEnvValue — if the string matches an environment variable it uses that, otherwise the literal. So the same config travels across environments with secrets in env vars.

fail-safe initnull on misconfigOptional

If payment.enabled is false, the provider block is missing, or required credentials don't resolve, the service logs a warning and returns null — the app still boots, just without payment routes, instead of crashing.

webhook secretStripeOptional

The Stripe webhook secret is threaded into the service so the webhook route can verify event signatures before trusting them; a missing secret is warned about loudly because it disables that verification.

Related sections

Storage Authentication Notification