Skip to main content

Paymentus Auth

Authentication client for Paymentus API services. This package handles JWT token management and authentication for Paymentus API endpoints.

Installation

pip install paymentus-auth

Usage

Basic Usage

import asyncio
from paymentus_auth import Auth, AuthConfig

async def main():
    # Initialize the auth client
    auth_config = AuthConfig(
        base_url='https://<environment>.paymentus.com',
        pre_shared_key='shared-256-bit-secret',
        scope=['xotp'],  # Base scopes
        tla='ABC'
    )

    auth_client = Auth(auth_config)

    # Fetch a token
    token = await auth_client.fetch_token()
    print(f"Token: {token}")
    
    # Check if token is expired
    is_token_expired = auth_client.is_token_expired()
    print(f"Token Expired: {is_token_expired}")
    
    # Get current token
    current_token = auth_client.get_current_token()
    print(f"Current Token: {current_token}")

asyncio.run(main())

Configuration Options

The Auth constructor accepts the following configuration:

Option Type Required Description
base_url string Yes Base URL for the Paymentus API, it varies based on the environment biller is in
pre_shared_key string Yes Pre-shared key for JWT signing
scope string[] Yes Array of API scopes (e.g., ['xotp', 'xotp:profile'])
tla string Yes Three-letter acronym for your application
aud string No Audience claim for the JWT (optional)
timeout number No Request timeout in milliseconds (default: 5000)
user_login string No User login identifier
pm_token string[] No Payment method tokens
payments_data list No Payment data for the transaction
pixels PixelType[] No Array of pixels to automatically add required scopes

scope or pixels — at least one is required.

Available Scopes

The SDK supports the following scopes:

  • xotp - Basic XOTP functionality
  • xotp:profile - Profile management
  • xotp:profile:read - Read profile data
  • xotp:profile:create - Create profiles
  • xotp:profile:update - Update profiles
  • xotp:profile:delete - Delete profiles
  • xotp:listProfiles - List profiles
  • xotp:payment - Payment processing
  • xotp:payment:history - Payment history
  • xotp:payment:void - Void or cancel payments
  • xotp:autopay - Autopay functionality
  • xotp:autopay:delete - Delete autopay settings
  • xotp:account - Link account to user
  • xotp:accounts - Account management
  • xotp:listAccounts - List accounts
  • paybotus - Paybotus functionality

Pixel Integration

The SDK provides automatic scope mapping for Paymentus pixels. When you specify pixels in the configuration, the SDK automatically adds the required scopes and validates required claims.

Basic example

import asyncio
from paymentus_auth import Auth, AuthConfig
from paymentus_auth.auth import PixelType

async def main():
    auth_client = Auth(AuthConfig(
        base_url='https://<environment>.paymentus.com',
        pre_shared_key='your-pre-shared-key',
        tla='ABC',
        aud='WEB_SDK',
        pixels=[PixelType.USER_CHECKOUT],
        user_login='user@example.com',
        payments_data=[{
            'accountNumber': '123456',
            'convFeeState': 'NY',
            'convFeeCountry': 'US'
        }]
    ))

    token = await auth_client.fetch_token()
    print(f"Token: {token}")

asyncio.run(main())

Pixel reference

  • tokenization-pixel

    • Scopes: xotp:profile
    • Claims: none required
  • list-wallets-pixel

    • Scopes: xotp:profile, xotp:listProfiles, xotp:profile:delete
    • Claims: user_login required
  • user-checkout-pixel

    • Scopes: xotp:profile, xotp:payment, xotp:listProfiles, xotp:listAccounts, xotp:profile:delete
    • Claims: user_login and payments_data required; pm_token optional
    • Optional scopes:
      • xotp:autopay — autopay enrollment during checkout
      • xotp:account — link account to user (single account only)
auth_client = Auth(AuthConfig(
    base_url='https://<environment>.paymentus.com',
    pre_shared_key='your-pre-shared-key',
    tla='ABC',
    pixels=[PixelType.USER_CHECKOUT],
    scope=['xotp:autopay', 'xotp:account'],
    user_login='user@example.com',
    payments_data=[{'accountNumber': '123456'}]
))
  • guest-checkout-pixel
    • Scopes: xotp:payment, xotp:listAccounts, xotp:profile
    • Claims: payments_data required
    • Automatically sets pmToken: ['anonymousPMOnly'] in the JWT
auth_client = Auth(AuthConfig(
    base_url='https://<environment>.paymentus.com',
    pre_shared_key='your-pre-shared-key',
    tla='ABC',
    pixels=[PixelType.GUEST_CHECKOUT],
    payments_data=[{'accountNumber': '123456'}]
))
  • user-autopay-pixel
    • Scopes: xotp:profile, xotp:autopay, xotp:payment, xotp:listProfiles, xotp:listAccounts, xotp:profile:delete
    • Claims: user_login and payments_data required; pm_token optional
    • Optional scope: xotp:account — link schedule account to user (single account only)
auth_client = Auth(AuthConfig(
    base_url='https://<environment>.paymentus.com',
    pre_shared_key='your-pre-shared-key',
    tla='ABC',
    pixels=[PixelType.USER_AUTOPAY],
    scope=['xotp:account'],
    user_login='user@example.com',
    payments_data=[{'accountNumber': '123456'}]
))
  • list-autopay-pixel

    • Scopes: xotp:profile, xotp:autopay, xotp:payment, xotp:listProfiles, xotp:listAccounts, xotp:profile:delete, xotp:autopay:delete
    • Claims: user_login and payments_data required
  • payment-history-pixel

    • Scopes: xotp:payment:history, xotp:payment, xotp:listProfiles
    • Claims: user_login and payments_data required
    • Optional scope: xotp:payment:void — cancel scheduled payments
auth_client = Auth(AuthConfig(
    base_url='https://<environment>.paymentus.com',
    pre_shared_key='your-pre-shared-key',
    tla='ABC',
    pixels=[PixelType.PAYMENT_HISTORY],
    scope=['xotp:payment:void'],
    user_login='user@example.com',
    payments_data=[{'accountNumber': '123456'}]
))
  • manage-payment-pixel
    • Scopes: xotp:payment, xotp:profile, xotp:listProfiles, xotp:payment:void
    • Claims: user_login and payments_data required
    • payments_data must include the reference or account number the user is allowed to manage
auth_client = Auth(AuthConfig(
    base_url='https://<environment>.paymentus.com',
    pre_shared_key='your-pre-shared-key',
    tla='ABC',
    pixels=[PixelType.MANAGE_PAYMENT],
    user_login='user@example.com',
    payments_data=[{'referenceNumber': '736165'}]
))

payments_data entries support accountNumber, referenceNumber, and optional convenience fee fields (convFeeState, convFeeCountry).

Error Handling

The package throws specific error types for different scenarios:

from paymentus_auth.errors import ConfigurationError, TokenError, NetworkError

try:
    token = await auth_client.fetch_token()
except ConfigurationError as e:
    print(f"Configuration Error: {e}")
except TokenError as e:
    print(f"Token Error: {e}")
except NetworkError as e:
    print(f"Network Error: {e}")

Advanced Usage

Using Multiple Scopes

import asyncio
from paymentus_auth import Auth, AuthConfig

async def main():
    auth_config = AuthConfig(
        base_url='https://<environment>.paymentus.com',
        pre_shared_key='shared-256-bit-secret',
        scope=['xotp:profile', 'xotp:payment'],  # Multiple scopes
        tla='ABC',
        aud='WEB_SDK'
    )
    
    auth_client = Auth(auth_config)
    token = await auth_client.fetch_token()
    print(f"Token: {token}")

asyncio.run(main())

Using Optional Fields

import asyncio
from paymentus_auth import Auth, AuthConfig

async def main():
    auth_config = AuthConfig(
        base_url='https://<environment>.paymentus.com',
        pre_shared_key='shared-256-bit-secret',
        scope=['xotp'],
        tla='ABC',
        aud='WEB_SDK',
        user_login='user@example.com',
        pm_token=['token1', 'token2'],
        payments_data=[{
            'account_number': '123456',
            'conv_fee_state': 'NY',
            'conv_fee_country': 'US'
        }]
    )
    
    auth_client = Auth(auth_config)
    token = await auth_client.fetch_token()
    print(f"Token: {token}")

asyncio.run(main())

API Reference

Auth Class

Constructor

Auth(config: AuthConfig)

Creates a new Auth client instance with the provided configuration.

Methods

fetch_token()
async fetch_token() -> str

Fetches a new JWT token from the Paymentus API. Returns a Promise that resolves to the token string.

get_current_token()
get_current_token() -> str or None

Returns the current token if available, or None if no token has been fetched.

is_token_expired()
is_token_expired() -> bool

Returns true if the current token is expired or no token is available.

Development

Building

python -m pip install -e .

Testing

python -m pytest

Disclaimer

These SDKs are intended for use with the URLs and keys that are provided to you for your company by Paymentus. If you do not have this information, please reach out to your implementation or account manager. If you are interested in learning more about the solutions that Paymentus provides, you can visit our website at paymentus.com. You can request access to our complete documentation at developer.paymentus.io. If you are currently not a customer or partner and would like to learn more about the solution and how you can get started with Paymentus, please contact us at https://www.paymentus.com/lets-talk/.

Contact us

If you have any questions or need assistance, please contact us at sdksupport@paymentus.com.

License

MIT

Metadata

Release files for paymentus-auth 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for paymentus-auth 1.0.1
File Size Uploaded Provenance Actions
paymentus_auth-1.0.1.tar.gz 12.1 kB Without provenance Details for paymentus_auth-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for paymentus-auth 1.0.1
File Interpreter ABI Platform Actions
paymentus_auth-1.0.1-py3-none-any.whl Python 3 none any Details for paymentus_auth-1.0.1-py3-none-any.whl

Total release size: 20.0 kB

Release files / paymentus_auth-1.0.1.tar.gz

Download URL paymentus_auth-1.0.1.tar.gz
Size 12.1 kB
Tags Source
SHA-256 checksum
How to use checksums
33c4856539bbbb2b4088eeac283571db1d52f2b95d4c7043a84b2e6c49885fcf
BLAKE2b-256 checksum
How to use checksums
736e9c417442e883046128f94ebeaad7b38a1b455e5630ebf43ccdcb850ac98c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / paymentus_auth-1.0.1-py3-none-any.whl

Download URL paymentus_auth-1.0.1-py3-none-any.whl
Size 7.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
039ca4ce2844580bfb7cdaf732a297b9de7fe99956ab48f25e78abee256614b0
BLAKE2b-256 checksum
How to use checksums
2dcc1cd914c31e3ba9c35b2aeb266d8acf916870a87d1557724f5f3f7f65bde1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for paymentus-auth 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page