@callback available?() :: boolean()

Checks if the provider is configured and available for use.

Returns true if:

• Provider is enabled in settings
• API credentials are configured
• Provider passed verification (if applicable)

Examples

iex> Stripe.available?()
true

@callback charge_payment_method(
  payment_method :: map(),
  amount :: Decimal.t(),
  opts :: keyword()
) :: {:ok, charge_result()} | {:error, term()}

Charges a saved payment method.

Used for subscription renewals. The payment method was previously saved during checkout or setup session.

Parameters

• payment_method - The saved payment method record
• amount - Amount to charge (Decimal)
• opts - Options:
  • :currency - Currency code (default: from payment method)
  • :description - Description for the charge
  • :invoice_uuid - Associated invoice UUID
  • :metadata - Additional metadata

Returns

• {:ok, charge_result} - Charge successful
• {:error, :card_declined} - Card was declined
• {:error, :payment_method_expired} - Payment method expired
• {:error, reason} - Other error

@callback create_checkout_session(invoice :: map(), opts :: keyword()) ::
  {:ok, checkout_session()} | {:error, term()}

Creates a checkout session for one-time payment.

This is used for paying invoices. The user is redirected to the provider's hosted checkout page where they enter payment details.

Parameters

• invoice - The invoice to pay (must include amount, currency, line_items)
• opts - Options:
  • :success_url - URL to redirect after successful payment
  • :cancel_url - URL to redirect if user cancels
  • :save_payment_method - Whether to save card for future use (default: false)

Returns

• {:ok, checkout_session} - Session created, redirect user to session.url
• {:error, reason} - Failed to create session

@callback create_refund(
  provider_transaction_id :: String.t(),
  amount :: Decimal.t() | nil,
  opts :: keyword()
) :: {:ok, refund_result()} | {:error, term()}

Creates a refund for a transaction.

Parameters

• provider_transaction_id - The provider's transaction/charge ID
• amount - Amount to refund (Decimal, nil for full refund)
• opts - Options:
  • :reason - Reason for refund
  • :metadata - Additional metadata

Returns

• {:ok, refund_result} - Refund created
• {:error, :already_refunded} - Transaction already refunded
• {:error, reason} - Refund failed

@callback create_setup_session(user :: map(), opts :: keyword()) ::
  {:ok, setup_session()} | {:error, term()}

Creates a setup session to save a payment method without charging.

Used when a user wants to add a payment method for future subscriptions without making an immediate payment.

Parameters

• user - The user to save payment method for
• opts - Options:
  • :success_url - URL to redirect after success
  • :cancel_url - URL to redirect if user cancels

Returns

• {:ok, setup_session} - Session created
• {:error, reason} - Failed to create session

@callback detach_payment_method(provider_payment_method_id :: String.t()) ::
  :ok | {:error, term()}

Detaches/removes a saved payment method from the provider.

Parameters

• provider_payment_method_id - The provider's payment method ID

Returns

• :ok - Payment method removed
• {:error, :not_found} - Payment method not found
• {:error, reason} - Failed to remove

@callback get_payment_method_details(provider_payment_method_id :: String.t()) ::
  {:ok, payment_method()} | {:error, term()}

Gets details of a saved payment method.

Parameters

• provider_payment_method_id - The provider's payment method ID

Returns

• {:ok, payment_method} - Payment method details
• {:error, :not_found} - Payment method not found
• {:error, reason} - Failed to get details

@callback handle_webhook_event(payload :: map()) ::
  {:ok, webhook_event()} | {:error, term()}

Handles and normalizes a webhook event payload.

Converts provider-specific event format to a normalized format that can be processed by WebhookProcessor.

Parameters

• payload - Decoded JSON payload from webhook

Returns

• {:ok, webhook_event} - Event parsed successfully
• {:error, :unknown_event} - Event type not recognized
• {:error, reason} - Failed to parse event

@callback provider_name() :: atom()

Returns the provider name as an atom.

Examples

iex> Stripe.provider_name()
:stripe

iex> PayPal.provider_name()
:paypal

@callback verify_webhook_signature(
  payload :: binary(),
  signature :: String.t(),
  secret :: String.t()
) :: :ok | {:error, :invalid_signature}

Verifies webhook signature to ensure request is from the provider.

Parameters

• payload - Raw request body as binary
• signature - Signature from request headers
• secret - Webhook secret for this provider

Returns

• :ok - Signature is valid
• {:error, :invalid_signature} - Signature verification failed