Client

Client

Main entry point for the merchants SDK.

Parameters:

Name	Type	Description	Default
provider	Provider | str	A :class:~merchants.providers.Provider instance or a registered provider key string (e.g. "stripe").	required
auth	AuthStrategy | None	Optional :class:~merchants.auth.AuthStrategy to apply to low-level requests made via :meth:request.	None
transport	Transport | None	Optional custom :class:~merchants.transport.Transport. Defaults to :class:~merchants.transport.RequestsTransport.	None
base_url	str	Optional base URL used by :meth:request.	''

Example::

from merchants import Client
from merchants.providers.stripe import StripeProvider

client = Client(provider=StripeProvider(api_key="sk_test_…"))
result = client.payments.create_checkout(
    amount="19.99",
    currency="USD",
    success_url="https://example.com/success",
    cancel_url="https://example.com/cancel",
)

Source code in merchants/client.py

class Client:
    """Main entry point for the merchants SDK.

    Args:
        provider: A :class:`~merchants.providers.Provider` instance **or**
            a registered provider key string (e.g. ``"stripe"``).
        auth: Optional :class:`~merchants.auth.AuthStrategy` to apply to
            low-level requests made via :meth:`request`.
        transport: Optional custom :class:`~merchants.transport.Transport`.
            Defaults to :class:`~merchants.transport.RequestsTransport`.
        base_url: Optional base URL used by :meth:`request`.

    Example::

        from merchants import Client
        from merchants.providers.stripe import StripeProvider

        client = Client(provider=StripeProvider(api_key="sk_test_…"))
        result = client.payments.create_checkout(
            amount="19.99",
            currency="USD",
            success_url="https://example.com/success",
            cancel_url="https://example.com/cancel",
        )
    """

    def __init__(
        self,
        provider: Provider | str,
        *,
        auth: AuthStrategy | None = None,
        transport: Transport | None = None,
        base_url: str = "",
    ) -> None:
        self._provider = get_provider(provider)
        self._auth = auth
        self._transport = transport or RequestsTransport()
        self._base_url = base_url.rstrip("/")
        self.payments = PaymentsResource(self._provider)

    def request(
        self,
        method: str,
        path: str,
        *,
        json: Any = None,
        params: dict[str, str] | None = None,
        headers: dict[str, str] | None = None,
        timeout: float = 30.0,
    ) -> HttpResponse:
        """Low-level HTTP escape hatch for provider-specific calls.

        Applies configured auth if present and uses the configured transport.

        Raises:
            :class:`~merchants.transport.TransportError`: On network failure.
        """
        hdrs: dict[str, str] = dict(headers or {})
        if self._auth:
            hdrs = self._auth.apply(hdrs)

        url = f"{self._base_url}{path}" if self._base_url else path
        return self._transport.send(
            method,
            url,
            headers=hdrs,
            json=json,
            params=params,
            timeout=timeout,
        )

Functions

request

request(
    method: str,
    path: str,
    *,
    json: Any = None,
    params: dict[str, str] | None = None,
    headers: dict[str, str] | None = None,
    timeout: float = 30.0,
) -> HttpResponse

Low-level HTTP escape hatch for provider-specific calls.

Applies configured auth if present and uses the configured transport.

Raises:

Type	Description
	class:~merchants.transport.TransportError: On network failure.

Source code in merchants/client.py

def request(
    self,
    method: str,
    path: str,
    *,
    json: Any = None,
    params: dict[str, str] | None = None,
    headers: dict[str, str] | None = None,
    timeout: float = 30.0,
) -> HttpResponse:
    """Low-level HTTP escape hatch for provider-specific calls.

    Applies configured auth if present and uses the configured transport.

    Raises:
        :class:`~merchants.transport.TransportError`: On network failure.
    """
    hdrs: dict[str, str] = dict(headers or {})
    if self._auth:
        hdrs = self._auth.apply(hdrs)

    url = f"{self._base_url}{path}" if self._base_url else path
    return self._transport.send(
        method,
        url,
        headers=hdrs,
        json=json,
        params=params,
        timeout=timeout,
    )

PaymentsResource

Resource object exposed as client.payments.

Provides hosted-checkout creation and payment status retrieval.

Source code in merchants/client.py

class PaymentsResource:
    """Resource object exposed as ``client.payments``.

    Provides hosted-checkout creation and payment status retrieval.
    """

    def __init__(self, provider: Provider) -> None:
        self._provider = provider

    def create_checkout(
        self,
        amount: Decimal | int | float | str,
        currency: str,
        success_url: str,
        cancel_url: str,
        metadata: dict[str, Any] | None = None,
        **kwargs: Any,
    ) -> CheckoutSession:
        """Create a hosted-checkout session.

        Args:
            amount: Payment amount; converted to :class:`~decimal.Decimal`.
            currency: ISO-4217 currency code (e.g. ``"USD"``).
            success_url: URL to redirect to after successful payment.
            cancel_url: URL to redirect to when the user cancels.
            metadata: Optional key-value pairs passed to the provider.
            **kwargs: Provider-specific keyword arguments (e.g. ``notify_url``).

        Returns:
            :class:`~merchants.models.CheckoutSession` - redirect the user to
            ``session.redirect_url``.

        Raises:
            :class:`~merchants.providers.UserError`: If the provider rejects the request.
        """
        return self._provider.create_checkout(
            Decimal(str(amount)),
            currency,
            success_url,
            cancel_url,
            metadata,
            **kwargs,
        )

    def get(self, payment_id: str) -> PaymentStatus:
        """Retrieve and normalise the status of a payment.

        Args:
            payment_id: Provider-specific payment / session identifier.

        Returns:
            :class:`~merchants.models.PaymentStatus`.
        """
        return self._provider.get_payment(payment_id)

Functions

create_checkout

create_checkout(
    amount: Decimal | int | float | str,
    currency: str,
    success_url: str,
    cancel_url: str,
    metadata: dict[str, Any] | None = None,
    **kwargs: Any,
) -> CheckoutSession

Create a hosted-checkout session.

Parameters:

Name	Type	Description	Default
amount	Decimal | int | float | str	Payment amount; converted to :class:~decimal.Decimal.	required
currency	str	ISO-4217 currency code (e.g. "USD").	required
success_url	str	URL to redirect to after successful payment.	required
cancel_url	str	URL to redirect to when the user cancels.	required
metadata	dict[str, Any] | None	Optional key-value pairs passed to the provider.	None
**kwargs	Any	Provider-specific keyword arguments (e.g. notify_url).	{}

Returns:

Type	Description
CheckoutSession	class:~merchants.models.CheckoutSession - redirect the user to
CheckoutSession	session.redirect_url.

Raises:

Type	Description
	class:~merchants.providers.UserError: If the provider rejects the request.

Source code in merchants/client.py

def create_checkout(
    self,
    amount: Decimal | int | float | str,
    currency: str,
    success_url: str,
    cancel_url: str,
    metadata: dict[str, Any] | None = None,
    **kwargs: Any,
) -> CheckoutSession:
    """Create a hosted-checkout session.

    Args:
        amount: Payment amount; converted to :class:`~decimal.Decimal`.
        currency: ISO-4217 currency code (e.g. ``"USD"``).
        success_url: URL to redirect to after successful payment.
        cancel_url: URL to redirect to when the user cancels.
        metadata: Optional key-value pairs passed to the provider.
        **kwargs: Provider-specific keyword arguments (e.g. ``notify_url``).

    Returns:
        :class:`~merchants.models.CheckoutSession` - redirect the user to
        ``session.redirect_url``.

    Raises:
        :class:`~merchants.providers.UserError`: If the provider rejects the request.
    """
    return self._provider.create_checkout(
        Decimal(str(amount)),
        currency,
        success_url,
        cancel_url,
        metadata,
        **kwargs,
    )

get

get(payment_id: str) -> PaymentStatus

Retrieve and normalise the status of a payment.

Parameters:

Name	Type	Description	Default
payment_id	str	Provider-specific payment / session identifier.	required

Returns:

Type	Description
PaymentStatus	class:~merchants.models.PaymentStatus.

Source code in merchants/client.py

def get(self, payment_id: str) -> PaymentStatus:
    """Retrieve and normalise the status of a payment.

    Args:
        payment_id: Provider-specific payment / session identifier.

    Returns:
        :class:`~merchants.models.PaymentStatus`.
    """
    return self._provider.get_payment(payment_id)