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 functionalityxotp:profile- Profile managementxotp:profile:read- Read profile dataxotp:profile:create- Create profilesxotp:profile:update- Update profilesxotp:profile:delete- Delete profilesxotp:listProfiles- List profilesxotp:payment- Payment processingxotp:payment:history- Payment historyxotp:payment:void- Void or cancel paymentsxotp:autopay- Autopay functionalityxotp:autopay:delete- Delete autopay settingsxotp:account- Link account to userxotp:accounts- Account managementxotp:listAccounts- List accountspaybotus- 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
- Scopes:
-
list-wallets-pixel- Scopes:
xotp:profile,xotp:listProfiles,xotp:profile:delete - Claims:
user_loginrequired
- Scopes:
-
user-checkout-pixel- Scopes:
xotp:profile,xotp:payment,xotp:listProfiles,xotp:listAccounts,xotp:profile:delete - Claims:
user_loginandpayments_datarequired;pm_tokenoptional - Optional scopes:
xotp:autopay— autopay enrollment during checkoutxotp:account— link account to user (single account only)
- Scopes:
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_datarequired - Automatically sets
pmToken: ['anonymousPMOnly']in the JWT
- Scopes:
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_loginandpayments_datarequired;pm_tokenoptional - Optional scope:
xotp:account— link schedule account to user (single account only)
- Scopes:
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_loginandpayments_datarequired
- Scopes:
-
payment-history-pixel- Scopes:
xotp:payment:history,xotp:payment,xotp:listProfiles - Claims:
user_loginandpayments_datarequired - Optional scope:
xotp:payment:void— cancel scheduled payments
- Scopes:
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_loginandpayments_datarequired payments_datamust include the reference or account number the user is allowed to manage
- Scopes:
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.