Skip to main content

​
Overview

The PaymentAdapter interface defines the contract that all payment provider implementations must follow. It provides a unified API for payment operations across different payment providers like Stripe, dLocal, and Paystack.

​
Interface Definition

interface PaymentAdapter {
  readonly name: string;
  readonly metadata: AdapterMetadata;
  charge(request: ChargeRequest): Promise<PaymentResult>;
  authorize(request: AuthorizeRequest): Promise<PaymentResult>;
  capture(request: CaptureRequest): Promise<PaymentResult>;
  refund(request: RefundRequest): Promise<RefundResult>;
  void(request: VoidRequest): Promise<VoidResult>;
  getStatus(transactionId: string): Promise<TransactionStatus>;
  listPaymentMethods(
    country: string,
    currency: string,
  ): Promise<PaymentMethodInfo[]>;
  handleWebhook?(
    payload: Buffer | string,
    headers: Record<string, string>,
  ): Promise<VaultEvent> | VaultEvent;
}

​
Properties

​
name
string
required
The unique identifier for the payment adapter (e.g., "stripe", "dlocal", "paystack").
​
metadata
AdapterMetadata
required
Static provider capability declaration used by routing validation.

​
Methods

​
charge

Process a direct charge (immediate payment capture). 
charge(request: ChargeRequest): Promise<PaymentResult>
​
request
ChargeRequest
required
The payment charge request details including amount, currency, payment method, and customer information.
Returns: Promise<PaymentResult> - The result of the charge operation.

​
authorize

Authorize a payment without capturing funds immediately. 
authorize(request: AuthorizeRequest): Promise<PaymentResult>
​
request
AuthorizeRequest
required
The authorization request details. Similar to ChargeRequest but does not capture funds.
Returns: Promise<PaymentResult> - The result of the authorization with status "authorized".

​
capture

Capture funds from a previously authorized payment. 
capture(request: CaptureRequest): Promise<PaymentResult>
​
request
CaptureRequest
required
The capture request containing the transaction ID and optional amount to capture.
Returns: Promise<PaymentResult> - The result of the capture operation.

​
refund

Refund a completed payment either fully or partially. 
refund(request: RefundRequest): Promise<RefundResult>
​
request
RefundRequest
required
The refund request containing transaction ID, optional amount, and reason.
Returns: Promise<RefundResult> - The result of the refund operation.

​
void

Cancel an authorized payment before capture. 
void(request: VoidRequest): Promise<VoidResult>
​
request
VoidRequest
required
The void request containing the transaction ID to cancel.
Returns: Promise<VoidResult> - The result of the void operation.

​
getStatus

Retrieve the current status of a transaction. 
getStatus(transactionId: string): Promise<TransactionStatus>
​
transactionId
string
required
The unique identifier of the transaction to query.
Returns: Promise<TransactionStatus> - Current transaction status including history.

​
listPaymentMethods

Get available payment methods for a specific country and currency combination. 
listPaymentMethods(
  country: string,
  currency: string,
): Promise<PaymentMethodInfo[]>
​
country
string
required
ISO 3166-1 alpha-2 country code (e.g., "US", "BR").
​
currency
string
required
ISO 4217 currency code (e.g., "USD", "BRL").
Returns: Promise<PaymentMethodInfo[]> - Array of available payment methods.

​
handleWebhook (Optional)

Process and verify incoming webhook events from the payment provider. 
handleWebhook?(
  payload: Buffer | string,
  headers: Record<string, string>,
): Promise<VaultEvent> | VaultEvent
​
payload
Buffer | string
required
The raw webhook payload received from the provider.
​
headers
Record<string, string>
required
HTTP headers from the webhook request, used for signature verification.
Returns: Promise<VaultEvent> | VaultEvent - Normalized webhook event. Throws: WebhookVerificationError if signature validation fails.

​
Adapter Constructor

All adapter classes must implement the PaymentAdapterConstructor interface: 
interface PaymentAdapterConstructor {
  new (config: Record<string, unknown>): PaymentAdapter;
  readonly supportedMethods: readonly string[];
  readonly supportedCurrencies: readonly string[];
  readonly supportedCountries: readonly string[];
}
The constructor receives a configuration object with adapter-specific settings (API keys, endpoints, etc.).

​
Implementation Examples

StripeAdapter

Stripe payment adapter implementation

DLocalAdapter

dLocal payment adapter for Latin America

PaystackAdapter

Paystack payment adapter for Africa
  • ChargeRequest - Request structure for direct charges
  • AuthorizeRequest - Request structure for payment authorization
  • CaptureRequest - Request structure for capturing authorized payments
  • RefundRequest - Request structure for refunds
  • VoidRequest - Request structure for voiding authorizations
  • PaymentResult - Standard payment operation result
  • RefundResult - Refund operation result
  • VoidResult - Void operation result
  • TransactionStatus - Transaction status query result
  • PaymentMethodInfo - Payment method information
  • VaultEvent - Normalized webhook event

Build docs developers (and LLMs) love

Get started for freeTalk to us