Custom provider

A payment provider adapter connects VitNode payments to a service with a hosted checkout page. Core owns the payment records, the webhook route, idempotent event handling and recovery; the adapter only talks to the provider and translates its objects. @vitnode/stripe (packages/stripe/src/index.ts) is the reference implementation.

ContractCopy Anchor Link

import type {
  PaymentCheckoutState,
  PaymentCreateCheckoutArgs,
  PaymentProviderApiPlugin,
  PaymentWebhookEvent,
} from '@vitnode/core/api/lib/payments/provider'

The factory should throw at startup when a required secret is missing, so an install never runs a half-configured provider.

createCheckout argumentsCopy Anchor Link

Core may call createCheckout again for the same attempt after a timeout or a lost response, with the same idempotencyKey, amount, currency, description and expiresAt. The provider must answer with the same checkout, not a new one. The return URLs come from the latest call; if the provider refuses a reused key because they changed, throw kind rejected, and the next call starts a fresh attempt. Core only replays while more than 35 minutes remain before expiresAt, and expiresAt is at most 23 hours away, which keeps replays inside the 24-hour idempotency window most providers offer. After that, an attempt whose checkout URL never reached the customer is expired instead of replayed.

Checkout stateCopy Anchor Link

interface PaymentCheckoutState {
  checkoutId: string // the provider's id
  paymentId: string | null // from the checkout's metadata
  status: 'pending' | 'processing' | 'succeeded' | 'failed' | 'expired'
  providerStatus: string // diagnostics only, max 50 chars
  amount: number | null // what the provider will charge, minor units
  currency: string | null
  livemode?: boolean | null
  expiresAt?: Date | null
  url?: string | null // while open
}

Report succeeded only when the provider confirms the money, processing when the customer finished but the payment is settling, and failed only for a final failure of that checkout. A declined card the customer can retry on the same page is still pending.

Core rejects state whose checkout id, paymentId, amount, currency or mode contradicts the stored payment, and logs it. Status only moves along pending → processing → succeeded | failed and pending → succeeded | failed | expired; final statuses never change.

WebhooksCopy Anchor Link

verifyWebhook receives the exact request bytes. Verify the signature over those bytes before parsing them.

type PaymentWebhookEvent =
  | { kind: 'checkout'; eventId: string; type: string; checkout: PaymentCheckoutState }
  | { kind: 'ignored'; eventId: string; type: string }

• Throw PaymentWebhookVerificationError for a bad signature, an expired timestamp or the wrong live/test mode. Core answers 400 and writes nothing.
• Return kind: "ignored" for verified events you do not handle, and for checkouts another instance created. Core answers 200.
• For kind: "checkout", core records (providerId, eventId) and applies the state in one transaction. A redelivery answers duplicate; a database error answers 500 so the provider retries.
• An event can arrive before core stored the checkout id. Core then matches it by checkout.paymentId, which must belong to the same instance.

The route is POST /api/@vitnode/core/payments/webhooks/{id} and answers { "outcome": "processed" | "duplicate" | "ignored" | "unmatched" | "mismatch" }.

ErrorsCopy Anchor Link

Throw PaymentProviderError from @vitnode/core/api/lib/payments/errors for provider failures. Never put secrets, card data or checkout URLs in the message.

Core logs rejected as a warning and the other kinds as errors. The reconciler never replays createCheckout: an attempt nobody retries is expired after 15 minutes, as described under recovery.

RecoveryCopy Anchor Link

• Missed webhook: getForUser({ refresh: true }) and the reconcile-payments cron job call retrieveCheckout. A provider that is down is skipped until the next run.
• Lost createCheckout response: the next call for the same reference, or a webhook carrying the payment id, attaches the checkout.
• Checkout never created: the reconciler expires the attempt after 15 minutes. Its URL never left the server, so nobody can pay it.

Several instances and testsCopy Anchor Link

Configure as many instances as you need; each gets its own id, secret and webhook URL. Core never moves a payment to another instance.

For automated tests, FakePaymentAdapter from @vitnode/core/api/adapters/payments/fake implements the contract in memory. Its settle(checkoutId, outcome) returns a signed webhook to post, and setUnavailable(true) simulates an outage. It moves no money, has no hosted page and refuses to start when NODE_ENV=production.

RelatedCopy Anchor Link