PayFanout API reference
    Preparing search index...

    Interface ServerPaymentAdapter

    interface ServerPaymentAdapter {
        pspName: string;
        cancelNativeSubscription?(
            input: CancelNativeSubscriptionInput,
        ): Promise<NativeSubscriptionRecord>;
        cancelPayment(
            pspPaymentId: string,
            idempotencyKey: string,
        ): Promise<PaymentInfo>;
        capturePayment?(
            pspPaymentId: string,
            amount: number | undefined,
            idempotencyKey: string,
        ): Promise<PaymentInfo>;
        chargeSavedPaymentMethod?(
            input: ChargeSavedPaymentMethodInput,
        ): Promise<PaymentInfo>;
        completePayment?(input: CompletePaymentInput): Promise<PaymentInfo>;
        createCustomer?(input: CreateCustomerInput): Promise<CustomerRef>;
        createNativeSubscription?(
            input: CreateNativeSubscriptionInput,
        ): Promise<NativeSubscriptionRecord>;
        createPaymentSession(
            input: CreatePaymentSessionInput,
        ): Promise<PaymentSession>;
        deleteSavedPaymentMethod?(
            pspCustomerId: string,
            token: string,
        ): Promise<void>;
        fetchEvents?(input?: FetchEventsInput): Promise<FetchEventsResult>;
        getCapabilities(): AdapterCapabilities;
        listNativeSubscriptions?(
            input?: ListNativeSubscriptionsInput,
        ): Promise<ListNativeSubscriptionsResult>;
        listPayments?(input?: ListPaymentsInput): Promise<ListPaymentsResult>;
        listRefunds?(input?: ListRefundsInput): Promise<ListRefundsResult>;
        listSavedPaymentMethods?(
            pspCustomerId: string,
        ): Promise<SavedPaymentMethod[]>;
        parseWebhookEvent(
            rawBody: string,
            headers: Record<string, string>,
        ): Promise<UnifiedWebhookEvent>;
        refundPayment(req: RefundRequest): Promise<RefundResult>;
        retrieveNativeSubscription?(
            input: RetrieveNativeSubscriptionInput,
        ): Promise<NativeSubscriptionRecord>;
        retrievePayment?(pspPaymentId: string): Promise<PaymentInfo>;
        retrieveRefund?(refundId: string): Promise<RefundInfo>;
        savePaymentMethod?(
            input: SavePaymentMethodInput,
        ): Promise<SavedPaymentMethod>;
        updatePaymentSession?(
            input: UpdatePaymentSessionInput,
        ): Promise<PaymentSession>;
        verifyCredentials?(): Promise<VerifyCredentialsResult>;
        verifyPaymentMethod?(input: VerifyPaymentMethodInput): Promise<PaymentInfo>;
        verifyWebhookSignature(
            rawBody: string,
            headers: Record<string, string>,
        ): Promise<boolean>;
    }

    Implemented by

    Index
    pspName
    cancelNativeSubscription? cancelPayment capturePayment? chargeSavedPaymentMethod? completePayment? createCustomer? createNativeSubscription? createPaymentSession deleteSavedPaymentMethod? fetchEvents? getCapabilities listNativeSubscriptions? listPayments? listRefunds? listSavedPaymentMethods? parseWebhookEvent refundPayment retrieveNativeSubscription? retrievePayment? retrieveRefund? savePaymentMethod? updatePaymentSession? verifyCredentials? verifyPaymentMethod? verifyWebhookSignature
    pspName: string

    • Resolves "canceled" only when the PSP confirms it. Under getCapabilities().modificationOutcome "asynchronous" the PSP merely acknowledges the request and the outcome arrives by webhook, so the returned status is "processing" — never an unconfirmed terminal state.

      Parameters

      • pspPaymentId: string
      • idempotencyKey: string

      Returns Promise<PaymentInfo>

    • Only present if getCapabilities().supportsManualCapture. Capture is the canonical double-charge operation — the idempotency key is REQUIRED, and under supportsMultiCapture each partial capture is its own charge with its own key.

      Parameters

      • pspPaymentId: string
      • amount: number | undefined
      • idempotencyKey: string

      Returns Promise<PaymentInfo>

    • Deletes by SavedPaymentMethod.token — the token is dead afterwards.

      Parameters

      • pspCustomerId: string
      • token: string

      Returns Promise<void>

    • Throws PayFanoutError (code "invalid_request") on unparseable payloads; maps genuinely unknown-but-valid event types to type "unknown" rather than throwing.

      Parameters

      • rawBody: string
      • headers: Record<string, string>

      Returns Promise<UnifiedWebhookEvent>

    • Only present if getCapabilities().supportsPaymentRetrieval. Push-only PSPs expose no read for a single payment — their hosts follow payment state through webhook deliveries instead.

      Parameters

      • pspPaymentId: string

      Returns Promise<PaymentInfo>

    • Poll a refund to a terminal state. Required whenever getCapabilities().supportsRefundRetrieval — refundPayment can return "pending". PSPs with no refund read declare the flag false and deliver the outcome by webhook instead.

      Parameters

      • refundId: string

      Returns Promise<RefundInfo>

    • Webhook handling — same adapter, separate concerns. Both async: future PSPs may need remote key retrieval; the contract stays uniform. MUST operate on the RAW request body bytes/string — re-serializing a parsed body breaks signatures (the conformance suite tests this).

      Parameters

      • rawBody: string
      • headers: Record<string, string>

      Returns Promise<boolean>

    Settings
    Member Visibility

    On This Page
    Properties
    Methods