SDKs
====

Official SDKs are available for the public Piaxis Payment API documented here.

They are open source and published, but they intentionally cover only the public
``/api`` payment surface. If you need a field or endpoint that has not yet been
promoted into the SDK API, use the raw REST endpoints documented in this site.

Python SDK
----------

- Package: ``piaxis-sdk``
- Import namespace: ``piaxis_sdk``
- PyPI: https://pypi.org/project/piaxis-sdk/
- Repository: https://github.com/piaxepay/python-sdk
- Install: ``pip install piaxis-sdk``
- Sandbox onboarding: https://github.com/piaxepay/python-sdk/blob/main/SANDBOX_ONBOARDING.md
- Examples:

  - https://github.com/piaxepay/python-sdk/blob/main/examples/direct_payment.py
  - https://github.com/piaxepay/python-sdk/blob/main/examples/oauth_flow.py
  - https://github.com/piaxepay/python-sdk/blob/main/examples/escrow_flow.py
  - https://github.com/piaxepay/python-sdk/blob/main/examples/disbursement_flow.py

TypeScript SDK
--------------

- Package: ``@piaxis/sdk``
- npm: https://www.npmjs.com/package/@piaxis/sdk
- Repository: https://github.com/piaxepay/typescript-sdk
- Install: ``npm install @piaxis/sdk``
- Sandbox onboarding: https://github.com/piaxepay/typescript-sdk/blob/main/SANDBOX_ONBOARDING.md
- Examples:

  - https://github.com/piaxepay/typescript-sdk/blob/main/examples/direct-payment.mjs
  - https://github.com/piaxepay/typescript-sdk/blob/main/examples/oauth-flow.mjs
  - https://github.com/piaxepay/typescript-sdk/blob/main/examples/escrow-flow.mjs
  - https://github.com/piaxepay/typescript-sdk/blob/main/examples/disbursement-flow.mjs

Coverage Notes
--------------

- Both SDKs target the public Payment API under ``https://api.gopiaxis.com/api``.
- The SDKs cover OAuth token exchange, OTP requests, payments, escrows, direct disbursements,
  and escrow disbursements.
- The default public mobile-money path is still ``request_otp`` followed by the money-moving call
  with the OTP carried in ``user_info.otp`` or, where supported by the route, ``mfa_code``.
- Direct payment and escrow use different field names on purpose:

  - direct payment: ``currency`` and a merchant collector inferred from the ``api-key``
  - escrow: ``currency_code`` and an optional ``receiver_id`` that defaults to the authenticated merchant account
- On the merchant direct-payment route, the authenticated merchant is the credited collector by default.
- On the public merchant escrow route, the authenticated merchant is also the default release destination.
- On direct disbursements, ``payment_method`` applies to the whole batch for external payouts, so mixed MTN/Airtel payouts should be sent as separate batches.
- External disbursement beneficiaries do not need Piaxis accounts; MTN and Airtel payouts use the beneficiary ``phone_number``.

- Keep treating the REST documentation as the source of truth for newly-added fields,
  advanced payloads, and endpoints that are not yet wrapped.

Marketplace Mapping
-------------------

If you are a platform serving many businesses, keep a trusted mapping from your
internal business id to the Piaxis account id used on the API:

- direct payment: authenticate as that merchant account; do not use ``recipient_id`` to switch collectors
- escrow: authenticate as that merchant account; omit ``receiver_id`` unless you are redundantly sending the same merchant account id
- payouts: send that account id inside ``recipients[].recipient_id``
- external mobile-money payout: omit ``recipient_id`` and send the beneficiary phone number with the batch ``payment_method``

Do not let end-user input pick raw Piaxis account ids directly.
Those ids are always Piaxis ``Account.id`` values, not ``MerchantProfile.id`` or ``UserProfile.id`` values.

Quick Reference
---------------

- Install with ``piaxis-sdk`` but import from ``piaxis_sdk`` in Python.
- TypeScript installs and imports from ``@piaxis/sdk``.
- Use the SDKs for the happy path, but fall back to the REST reference when you need fields or
  endpoints that are documented publicly but not yet wrapped by SDK helpers.

Related References
------------------

- Public docs: ``https://api.gopiaxis.com/api/docs/``
- Endpoint catalog: :doc:`endpoints`
- Authentication: :doc:`authentication`
- Payments: :doc:`payments`
- Escrows: :doc:`escrow`
- Disbursements: :doc:`disbursements`
- Webhooks: :doc:`webhooks`