gimacpay 0.1.0__py3-none-any.whl

gimacpay/__init__.py

@@ -0,0 +1,119 @@
+"""gimacpay -- a Python client for GIMACPAY, the CEMAC interbank payment network.
+
+GIMACPAY is operated by GIMAC (Groupement Interbancaire Monétique de l'Afrique
+Centrale) and connects 59 commercial banks, six national treasuries and the
+mobile-money wallets of the six CEMAC member states -- Cameroun, Tchad,
+République centrafricaine, Guinée équatoriale, Gabon and Congo. Since July 2026
+it also carries the BEAC's common QR code, and since July 2026 it is connected
+to PAPSS for continental cross-border settlement.
+
+This library implements the participant API as published in
+``GIMACPay Swagger for payments issuers`` version 1.8 (specification file
+1.10).
+
+Zero runtime dependencies. See ``SECURITY.md`` for why that is deliberate.
+
+Quick start::
+
+    from gimacpay import GimacPayClient, wallet_to_wallet
+
+    client = GimacPayClient(
+        base_url="https://.../stdendpointfacade/v1/external",
+        client_id="...", client_secret="...",
+        username="...", password="...",
+        default_dial_code="237",
+    )
+
+    payment = client.send_and_resolve(
+        wallet_to_wallet(
+            amount=500,
+            walletsource="237699947943",
+            walletdestination="2356789009",
+            tomember="22001",
+            issuertrxref="ORD-2026-0001",
+        )
+    )
+    print(payment.state)   # ACCEPTED, REJECTED, ... -- never a guess
+
+The one rule this library is built around, taken from the specification's
+description of ``/payment/send``::
+
+    Participants should not guess the state if it's not given by GIMACPay.
+"""
+
+from __future__ import annotations
+
+from .builders import (
+    account_inquiry,
+    bill_inquiry,
+    bill_payment,
+    build,
+    cash_deposit,
+    cash_in,
+    cash_out,
+    merchant_purchase,
+    mobile_reload,
+    request_to_pay,
+    wallet_to_wallet,
+)
+from .client import REFERENCE_SERVER, GimacPayClient
+from .errors import (
+    GimacPayAuthError,
+    GimacPayConfigError,
+    GimacPayError,
+    GimacPayForbiddenError,
+    GimacPayProtocolError,
+    GimacPayTransportError,
+    PaymentRejected,
+    PaymentStateUnknown,
+)
+from .intents import ALL_INTENTS, Intent, is_known, required_fields
+from .models import TERMINAL_STATES, AccountInfo, Bill, CustomerData, Payment, PaymentState
+from .money import CEMAC_DIAL_CODES, CURRENCY_XAF, normalise_phone, validate_amount
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # client
+    "GimacPayClient",
+    "REFERENCE_SERVER",
+    # builders
+    "wallet_to_wallet",
+    "merchant_purchase",
+    "request_to_pay",
+    "cash_in",
+    "cash_deposit",
+    "cash_out",
+    "bill_inquiry",
+    "bill_payment",
+    "mobile_reload",
+    "account_inquiry",
+    "build",
+    # intents
+    "Intent",
+    "ALL_INTENTS",
+    "is_known",
+    "required_fields",
+    # models
+    "Payment",
+    "PaymentState",
+    "TERMINAL_STATES",
+    "AccountInfo",
+    "Bill",
+    "CustomerData",
+    # helpers
+    "CURRENCY_XAF",
+    "CEMAC_DIAL_CODES",
+    "normalise_phone",
+    "validate_amount",
+    # errors
+    "GimacPayError",
+    "GimacPayConfigError",
+    "GimacPayTransportError",
+    "GimacPayAuthError",
+    "GimacPayForbiddenError",
+    "PaymentRejected",
+    "PaymentStateUnknown",
+    "GimacPayProtocolError",
+]

gimacpay/__main__.py

@@ -0,0 +1,217 @@
+"""Command line entry point: ``gimacpay``.
+
+Deliberately conservative. Sending money from a shell is easy to do by
+accident, so :command:`send` refuses to act without an explicit ``--confirm``,
+and :command:`build` prints the payload without sending anything.
+
+Usage::
+
+    gimacpay intents                 # what the specification defines
+    gimacpay intents mobile_transfer # required fields for one intent
+    gimacpay doctor                  # check config and authenticate
+    gimacpay build --intent mobile_transfer --amount 500 --walletsource ... \
+                   --walletdestination ... --tomember 22001 --ref ORD-1
+    gimacpay send  ... --confirm
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+from . import __version__
+from .builders import build as build_request
+from .client import GimacPayClient
+from .errors import GimacPayError, PaymentStateUnknown
+from .intents import ALL_INTENTS, REQUIRED_FIELDS, required_fields
+
+__all__ = ["main"]
+
+_ENV_PREFIX = "GIMACPAY_"
+
+#: Fields the CLI passes through as integers rather than strings.
+_INT_FIELDS = frozenset({"amount", "validityduration", "pagesize", "firstelement"})
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gimacpay",
+        description="Client for the GIMACPAY participant API (CEMAC).",
+    )
+    parser.add_argument("--version", action="version", version=f"gimacpay {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    intents = sub.add_parser("intents", help="list the intents in specification 1.10")
+    intents.add_argument("intent", nargs="?", help="show the required fields for one intent")
+
+    sub.add_parser("doctor", help="check configuration and authenticate")
+
+    for name, help_text in (
+        ("build", "build a request and print it, without sending"),
+        ("send", "send a request (requires --confirm)"),
+    ):
+        cmd = sub.add_parser(name, help=help_text)
+        cmd.add_argument("--intent", required=True)
+        cmd.add_argument("--ref", required=True, dest="issuertrxref")
+        cmd.add_argument("--amount", type=int)
+        cmd.add_argument("--currency", default="950")
+        cmd.add_argument("--tomember")
+        cmd.add_argument("--walletsource")
+        cmd.add_argument("--walletdestination")
+        cmd.add_argument("--sendermobile")
+        cmd.add_argument("--receivermobile")
+        cmd.add_argument("--validityduration", type=int)
+        cmd.add_argument("--description")
+        cmd.add_argument("--extra", help="extra fields as a JSON object")
+        cmd.add_argument(
+            "--wait",
+            type=float,
+            default=0.0,
+            help="seconds to follow the payment to a terminal state",
+        )
+        if name == "send":
+            cmd.add_argument(
+                "--confirm",
+                action="store_true",
+                help="required: without it nothing is sent",
+            )
+
+    return parser
+
+
+def _client_from_env() -> GimacPayClient:
+    """Build a client from ``GIMACPAY_*`` environment variables."""
+    missing = [
+        key
+        for key in ("CLIENT_ID", "CLIENT_SECRET", "USERNAME", "PASSWORD")
+        if not os.environ.get(_ENV_PREFIX + key)
+    ]
+    if missing:
+        raise SystemExit(
+            "missing environment variables: " + ", ".join(_ENV_PREFIX + key for key in missing)
+        )
+
+    return GimacPayClient(
+        base_url=os.environ.get(_ENV_PREFIX + "BASE_URL", None) or None or "",
+        client_id=os.environ[_ENV_PREFIX + "CLIENT_ID"],
+        client_secret=os.environ[_ENV_PREFIX + "CLIENT_SECRET"],
+        username=os.environ[_ENV_PREFIX + "USERNAME"],
+        password=os.environ[_ENV_PREFIX + "PASSWORD"],
+        default_dial_code=os.environ.get(_ENV_PREFIX + "DIAL_CODE"),
+    )
+
+
+def _payload(args: argparse.Namespace) -> dict[str, Any]:
+    fields: dict[str, Any] = {
+        "issuertrxref": args.issuertrxref,
+        "amount": args.amount,
+        "currency": args.currency,
+        "tomember": args.tomember,
+        "walletsource": args.walletsource,
+        "walletdestination": args.walletdestination,
+        "sendermobile": args.sendermobile,
+        "receivermobile": args.receivermobile,
+        "validityduration": args.validityduration,
+        "description": args.description,
+    }
+    if args.extra:
+        try:
+            extra = json.loads(args.extra)
+        except json.JSONDecodeError as exc:
+            raise SystemExit(f"--extra is not valid JSON: {exc}") from exc
+        if not isinstance(extra, dict):
+            raise SystemExit("--extra must be a JSON object")
+        fields.update(extra)
+
+    return build_request(args.intent, **{k: v for k, v in fields.items() if v is not None})
+
+
+def _cmd_intents(intent: str | None) -> int:
+    if intent:
+        if intent not in ALL_INTENTS:
+            print(f"unknown intent {intent!r} in specification 1.10", file=sys.stderr)
+            print("known intents:", ", ".join(sorted(ALL_INTENTS)), file=sys.stderr)
+            return 1
+        print(f"{intent}:")
+        for name in required_fields(intent):
+            print(f"  - {name}")
+        return 0
+
+    for name in sorted(ALL_INTENTS):
+        fields = REQUIRED_FIELDS.get(name)
+        suffix = f"  ({len(fields)} required)" if fields else "  (no builder; use build())"
+        print(f"{name}{suffix}")
+    print(f"\n{len(ALL_INTENTS)} intents, specification version 1.10", file=sys.stderr)
+    return 0
+
+
+def _cmd_doctor() -> int:
+    client = _client_from_env()
+    print(f"base_url : {client.base_url}")
+    print(f"username : {client.username}")
+    print("authenticating...")
+    client.authenticate()
+    print("OK: authenticated")
+    return 0
+
+
+def _cmd_build(args: argparse.Namespace) -> int:
+    print(json.dumps(_payload(args), indent=2, ensure_ascii=False))
+    return 0
+
+
+def _cmd_send(args: argparse.Namespace) -> int:
+    if not args.confirm:
+        print(
+            "refusing to send without --confirm.\n"
+            "Review the payload first with:\n"
+            "  gimacpay build ...",
+            file=sys.stderr,
+        )
+        return 2
+
+    client = _client_from_env()
+    payload = _payload(args)
+
+    if args.wait > 0:
+        payment = client.send_and_resolve(payload, timeout=args.wait)
+    else:
+        payment = client.send_payment(payload)
+
+    print(json.dumps(payment.raw, indent=2, ensure_ascii=False))
+    print(f"\nstate: {payment.state}", file=sys.stderr)
+    if not payment.is_terminal:
+        print(
+            f"note: not terminal. Inquire with:\n  issuertrxref={payment.issuertrxref}",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+
+    handlers = {
+        "intents": lambda: _cmd_intents(getattr(args, "intent", None)),
+        "doctor": _cmd_doctor,
+        "build": lambda: _cmd_build(args),
+        "send": lambda: _cmd_send(args),
+    }
+
+    try:
+        return handlers[args.command]()
+    except PaymentStateUnknown as exc:
+        print(f"STATE UNKNOWN: {exc}", file=sys.stderr)
+        print("the payment is not failed -- inquire before acting", file=sys.stderr)
+        return 3
+    except GimacPayError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

gimacpay/builders.py

@@ -0,0 +1,339 @@
+"""Request builders -- one function per ``intent`` you are likely to need.
+
+Why these exist: ``/payment/send`` accepts a ``oneOf`` of 24 schemas selected
+by the ``intent`` field. Building that dictionary by hand means remembering a
+discriminator string and a set of required fields, in a system where a typo
+moves money. These helpers set ``intent`` themselves, validate the amount, and
+normalise phone numbers.
+
+Every builder returns a plain ``dict``. Nothing here is opaque: you can always
+print the result, amend it, and pass it to
+:meth:`~gimacpay.client.GimacPayClient.send_payment` yourself.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from .intents import Intent
+from .money import CURRENCY_XAF, normalise_phone, validate_amount
+
+__all__ = [
+    "wallet_to_wallet",
+    "merchant_purchase",
+    "request_to_pay",
+    "cash_in",
+    "cash_deposit",
+    "cash_out",
+    "bill_inquiry",
+    "bill_payment",
+    "mobile_reload",
+    "account_inquiry",
+    "build",
+]
+
+
+def _base(intent: str, issuertrxref: str, **rest: Any) -> dict[str, Any]:
+    """Assemble a request, dropping ``None`` values.
+
+    ``issuertrxref`` is your own reference and the only handle you have on the
+    payment afterwards -- :meth:`GimacPayClient.await_state` looks it up. It is
+    required on every request, so it is required here.
+    """
+    if not issuertrxref:
+        raise ValueError(
+            "issuertrxref is required: it is the only reference you can use to "
+            "inquire about this payment later"
+        )
+    payload: dict[str, Any] = {"intent": intent, "issuertrxref": str(issuertrxref)}
+    payload.update({k: v for k, v in rest.items() if v is not None})
+    return payload
+
+
+def _phone(value: str | None, field: str) -> str | None:
+    """Normalise a phone number, refusing to guess a missing country code."""
+    if value is None:
+        return None
+    try:
+        return normalise_phone(value)
+    except ValueError as exc:
+        raise ValueError(f"{field}: {exc}") from exc
+
+
+def wallet_to_wallet(
+    *,
+    amount: object,
+    walletsource: str,
+    walletdestination: str,
+    tomember: str,
+    issuertrxref: str,
+    description: str | None = None,
+    currency: str = CURRENCY_XAF,
+) -> dict[str, Any]:
+    """Move money from one mobile wallet to another (``mobile_transfer``)."""
+    return _base(
+        Intent.MOBILE_TRANSFER,
+        issuertrxref,
+        amount=validate_amount(amount),
+        currency=currency,
+        walletsource=_phone(walletsource, "walletsource"),
+        walletdestination=_phone(walletdestination, "walletdestination"),
+        tomember=str(tomember),
+        description=description,
+    )
+
+
+def merchant_purchase(
+    *,
+    amount: object,
+    walletsource: str,
+    walletdestination: str,
+    tomember: str,
+    issuertrxref: str,
+    description: str | None = None,
+    currency: str = CURRENCY_XAF,
+) -> dict[str, Any]:
+    """Pay a merchant from a wallet (``merchant_purchase``).
+
+    ``walletdestination`` is the merchant's wallet identifier, which in the
+    specification's example is a short numeric code rather than a phone number
+    -- so it is passed through untouched.
+    """
+    return _base(
+        Intent.MERCHANT_PURCHASE,
+        issuertrxref,
+        amount=validate_amount(amount),
+        currency=currency,
+        walletsource=_phone(walletsource, "walletsource"),
+        walletdestination=str(walletdestination),
+        tomember=str(tomember),
+        description=description,
+    )
+
+
+def request_to_pay(
+    *,
+    amount: object,
+    walletsource: str,
+    walletdestination: str,
+    tomember: str,
+    issuertrxref: str,
+    currency: str = CURRENCY_XAF,
+) -> dict[str, Any]:
+    """Ask a payer to pay you (``request_to_pay``).
+
+    Note the direction: ``walletsource`` is *your* identifier and
+    ``walletdestination`` is the person being asked to pay.
+    """
+    return _base(
+        Intent.REQUEST_TO_PAY,
+        issuertrxref,
+        amount=validate_amount(amount),
+        currency=currency,
+        walletsource=str(walletsource),
+        walletdestination=_phone(walletdestination, "walletdestination"),
+        tomember=str(tomember),
+    )
+
+
+def cash_in(
+    *,
+    amount: object,
+    walletdestination: str,
+    tomember: str,
+    teller: str,
+    pointofservice: str,
+    issuertrxref: str,
+    currency: str = CURRENCY_XAF,
+) -> dict[str, Any]:
+    """Credit a wallet with cash handed over at a counter (``cash_in``)."""
+    return _base(
+        Intent.CASH_IN,
+        issuertrxref,
+        amount=validate_amount(amount),
+        currency=currency,
+        walletdestination=_phone(walletdestination, "walletdestination"),
+        tomember=str(tomember),
+        teller=str(teller),
+        pointofservice=str(pointofservice),
+    )
+
+
+def cash_deposit(
+    *,
+    amount: object,
+    walletdestination: str,
+    tomember: str,
+    issuertrxref: str,
+    currency: str = CURRENCY_XAF,
+) -> dict[str, Any]:
+    """Deposit cash into a wallet (``cash_deposit``)."""
+    return _base(
+        Intent.CASH_DEPOSIT,
+        issuertrxref,
+        amount=validate_amount(amount),
+        currency=currency,
+        walletdestination=_phone(walletdestination, "walletdestination"),
+        tomember=str(tomember),
+    )
+
+
+def cash_out(
+    *,
+    amount: object,
+    walletsource: str,
+    issuertrxref: str,
+    validityduration: int,
+    receiver_firstname: str,
+    receiver_secondname: str,
+    merchantid: str | None = None,
+    currency: str = CURRENCY_XAF,
+) -> dict[str, Any]:
+    """Withdraw cash from a wallet (``cash_out``).
+
+    ``validityduration`` is in seconds: how long the withdrawal voucher stays
+    usable. The specification's examples use 4500.
+    """
+    receiver: dict[str, Any] = {
+        "firstname": receiver_firstname,
+        "secondname": receiver_secondname,
+    }
+    if merchantid is not None:
+        receiver["merchantid"] = str(merchantid)
+
+    return _base(
+        Intent.CASH_OUT,
+        issuertrxref,
+        amount=validate_amount(amount),
+        currency=currency,
+        walletsource=str(walletsource),
+        validityduration=int(validityduration),
+        receivercustomerdata=[receiver],
+    )
+
+
+def bill_inquiry(
+    *,
+    walletsource: str,
+    tomember: str,
+    issuertrxref: str,
+    query_ref: str,
+    contract_ref: str,
+    service_ref: str,
+) -> dict[str, Any]:
+    """Ask a biller what is owed, before paying (``bill_inquiry``).
+
+    No ``amount``: the point of an inquiry is to discover it.
+    """
+    return _base(
+        Intent.BILL_INQUIRY,
+        issuertrxref,
+        tomember=str(tomember),
+        walletsource=str(walletsource),
+        billInquiryData={
+            "queryRef": str(query_ref),
+            "contractRef": str(contract_ref),
+            "serviceRef": str(service_ref),
+        },
+    )
+
+
+def bill_payment(
+    *,
+    amount: object,
+    walletsource: str,
+    tomember: str,
+    service: str,
+    bill_refs: Sequence[str],
+    issuertrxref: str,
+    currency: str = CURRENCY_XAF,
+) -> dict[str, Any]:
+    """Pay one or more bills identified by reference (``bill_payment``).
+
+    The ``billRef`` values come from :func:`bill_inquiry` -- the specification's
+    example is an ENEO reference of the form
+    ``S-112-950-ENEO-10039-<hash>``.
+    """
+    refs: list[str] = [str(ref) for ref in bill_refs]
+    if not refs:
+        raise ValueError("bill_refs must contain at least one bill reference")
+
+    return _base(
+        Intent.BILL_PAYMENT,
+        issuertrxref,
+        amount=validate_amount(amount),
+        currency=currency,
+        walletsource=str(walletsource),
+        tomember=str(tomember),
+        service=str(service),
+        billList=[{"billRef": ref} for ref in refs],
+    )
+
+
+def mobile_reload(
+    *,
+    amount: object,
+    sendermobile: str,
+    receivermobile: str,
+    tomember: str,
+    issuertrxref: str,
+    currency: str = CURRENCY_XAF,
+) -> dict[str, Any]:
+    """Buy airtime for a number (``mobile_reload``)."""
+    return _base(
+        Intent.MOBILE_RELOAD,
+        issuertrxref,
+        amount=validate_amount(amount),
+        currency=currency,
+        sendermobile=_phone(sendermobile, "sendermobile"),
+        receivermobile=_phone(receivermobile, "receivermobile"),
+        tomember=str(tomember),
+    )
+
+
+def account_inquiry(
+    *,
+    tomember: str,
+    issuertrxref: str,
+    walletdestination: str | None = None,
+    dstaccount: str | None = None,
+    dstaccount_type: str = "ACCOUNT",
+) -> dict[str, Any]:
+    """Resolve a wallet or account before sending to it (``account_inquiry``).
+
+    Pass exactly one of ``walletdestination`` or ``dstaccount``. The
+    specification has two worked examples for this intent, one for each.
+    """
+    if (walletdestination is None) == (dstaccount is None):
+        raise ValueError("pass exactly one of walletdestination or dstaccount")
+
+    payload = _base(Intent.ACCOUNT_INQUIRY, issuertrxref, tomember=str(tomember))
+    if walletdestination is not None:
+        payload["walletdestination"] = _phone(walletdestination, "walletdestination")
+    else:
+        payload["dstaccounts"] = [{"iden": str(dstaccount), "type": dstaccount_type}]
+    return payload
+
+
+def build(intent: str, /, **fields: Any) -> dict[str, Any]:
+    """Build a request for any intent, including ones this module does not cover.
+
+    Use this for the eight remittance intents and anything GIMACPay adds later.
+    It validates the amount if one is supplied, but it does not know the
+    required fields for an intent it has no builder for -- so it cannot protect
+    you from an incomplete request. Prefer the named builders.
+
+    Example::
+
+        build("inc_acc_remit",
+              issuertrxref="R-1", amount=750, tomember="10029",
+              sendermobile="+336575950505",
+              dstaccounts=[{"iden": "100291525478502", "type": "ACCOUNT"}])
+    """
+    if not intent:
+        raise ValueError("intent is required")
+    if "amount" in fields:
+        fields["amount"] = validate_amount(fields["amount"])
+    fields.setdefault("currency", CURRENCY_XAF)
+    return _base(intent, fields.pop("issuertrxref", ""), **fields)