enfuce-nextgen-sdk 0.0.11

Enfuce nextgen client SDK (Python). One sub-package per API under enfuce_nextgen.

enfuce-nextgen-sdk

Enfuce nextgen client SDK for Python. Each API is an isolated sub-package under enfuce_nextgen, so identically-named models across APIs never collide.

Installation

pip install enfuce-nextgen-sdk

Usage

Every API module ships a fluent <Module>Client (e.g. CardClient, ExchangeRateClient) that builds the ApiClient, installs OAuth, applies the base URL, and exposes each API. Every request is authenticated with an OAuth2 client_credentials bearer token:

from enfuce_nextgen.oauth import client_credentials
from enfuce_nextgen.config import TenantEnvironment, issuer_base_url, token_url
from enfuce_nextgen.card import CardClient

# Set the tenant + environment once; the config helper derives every base URL (and the token URL) from it.
te = TenantEnvironment("<tenant>", "<environment>")

# One token manager (cached client-credentials grant) — reuse it across every module.
clientCredentialsManager = client_credentials(
    token_url(te),
    "<client-id>", "<client-secret>", scopes=["issuer/cardholder.read"],
)

client = (
    CardClient.builder()
    .base_url(issuer_base_url(te))
    .oauth(clientCredentialsManager)                                # token on every request + 401 retry
    .configure(lambda c: setattr(c, "proxy", "http://proxy:8080")) # optional: TLS, retries, pool …
    .build()
)

card = client.get_card_api().get_card(card_id, x_audit_user="[e-mail]")

environment is the target platform — e.g. ext-uat1-sandbox (sandbox) or eu.live.prod (production). One clientCredentialsManager authenticates every module, so build it once and reuse it across all your clients. See Client customization for transport tuning (timeouts, proxy, TLS, pool).

Keeping the token URL separate from the client identity? Pass a ClientCredentials — e.g. with the config helper deriving the URL:

from enfuce_nextgen.oauth import ClientCredentials, client_credentials
from enfuce_nextgen.config import TenantEnvironment, token_url

te = TenantEnvironment("<tenant>", "<environment>")
clientCredentialsManager = client_credentials(
    token_url(te),
    ClientCredentials("<client-id>", "<client-secret>", ["issuer/cardholder.read"]),
)

Inspecting scopes

available_scopes(...) discovers the scopes the client is entitled to — it requests a token with no scope narrowing and returns the granted scopes (sorted, de-duplicated). scopes_of(...) decodes the granted scopes from any JWT you already hold. Both return an empty list for an opaque (non-JWT) token and never raise.

from enfuce_nextgen.oauth import available_scopes, scopes_of
from enfuce_nextgen.config import token_url

# The client's full entitlement (a live, uncached token request):
available = available_scopes(token_url(te), "<client-id>", "<client-secret>")

# Or decode the scopes granted on a token you already hold:
granted = scopes_of(clientCredentialsManager.get_token())

Client customization

.configure(lambda c: …) on any <Module>Client builder hands you the underlying Configuration for transport settings — proxy, TLS/SSL, retries, connection pool, etc. It composes with .oauth(...).

client = (
    CardClient.builder()
    .base_url(issuer_base_url(te))
    .oauth(clientCredentialsManager)
    .configure(lambda c: setattr(c, "proxy", "http://proxy:8080"))
    .build()
)

Prefer the lower level? enfuce_nextgen.oauth.oauth_configuration / oauth_api_client build an OAuth-enabled Configuration / ApiClient you can pass to an API class directly.

Configuring timeouts

Timeouts are per request in the Python client (not a Configuration setting) — pass _request_timeout (a total in seconds, or a (connect, read) tuple) on any call:

client.get_card_api().get_card(card_id, x_audit_user="[e-mail]", _request_timeout=10)
client.get_card_api().get_card(card_id, x_audit_user="[e-mail]", _request_timeout=(3, 10))

API modules

Each module builds the same way — set its base URL with the matching accessor (issuer_base_url, processor_base_url, or exchange_rate_base_url) and reuse the shared clientCredentialsManager. Snippets assume te and clientCredentialsManager are in scope.

cardholder — issuer_base_url

from enfuce_nextgen.config import issuer_base_url
from enfuce_nextgen.cardholder import CardholderClient

client = CardholderClient.builder().base_url(issuer_base_url(te)).oauth(clientCredentialsManager).build()

holder = client.get_cardholder_api().get_cardholder_by_id(cardholder_id, x_audit_user="[e-mail]")
cards = client.get_cards_by_cardholder_id_api().get_cards_by_cardholder_id(cardholder_id, x_audit_user="[e-mail]")

card — issuer_base_url

from enfuce_nextgen.config import issuer_base_url
from enfuce_nextgen.card import CardClient

client = CardClient.builder().base_url(issuer_base_url(te)).oauth(clientCredentialsManager).build()

card = client.get_card_api().get_card(card_id, x_audit_user="[e-mail]")
client.update_card_api().activate_card(card_id, x_audit_user="[e-mail]")

wallet — issuer_base_url

from enfuce_nextgen.config import issuer_base_url
from enfuce_nextgen.wallet import WalletClient

client = WalletClient.builder().base_url(issuer_base_url(te)).oauth(clientCredentialsManager).build()

tokens = client.get_tokens_api().get_tokens(card_id, x_audit_user="[e-mail]")

pin — issuer_base_url

from enfuce_nextgen.config import issuer_base_url
from enfuce_nextgen.pin import PinClient

client = PinClient.builder().base_url(issuer_base_url(te)).oauth(clientCredentialsManager).build()

view = client.pin_operations_using_pki_api().view_pin(view_pin_request_body, x_audit_user="[e-mail]")

exchange_rate — exchange_rate_base_url

from enfuce_nextgen.config import exchange_rate_base_url
from enfuce_nextgen.exchange_rate import ExchangeRateClient

client = ExchangeRateClient.builder().base_url(exchange_rate_base_url(te)).oauth(clientCredentialsManager).build()

currencies = client.get_ecb_supported_currencies_api().get_ecb_supported_currencies_v1()
rate = client.get_ecb_exchange_rate_api().get_ecb_rate_v1("EUR", "USD")

threeds — processor_base_url

from enfuce_nextgen.config import processor_base_url
from enfuce_nextgen.threeds import ThreedsClient

client = ThreedsClient.builder().base_url(processor_base_url(te)).oauth(clientCredentialsManager).build()

client.three_ds_api().handle_authentication_challenge_result(challenge_result_body)

cards — processor_base_url

from enfuce_nextgen.config import processor_base_url
from enfuce_nextgen.cards import CardsClient

client = CardsClient.builder().base_url(processor_base_url(te)).oauth(clientCredentialsManager).build()

client.cards_api().reset_pin_counter(card_id, sequence_number)

Webhooks

These are the calls Enfuce makes to you: you host the endpoint and Enfuce POSTs to it. Such modules provide only the payload models — there is no client to call, since your app receives these rather than requesting them. Parse the inbound request body with the pydantic models (from_json / from_dict):

from enfuce_nextgen.issuer_events import CardEvent

event = CardEvent.from_json(payload)

authorisation_control is synchronous — Enfuce expects an approve/decline decision in the response, so you both consume a model and return one:

from enfuce_nextgen.authorisation_control import AuthRequestBody, AuthResponseBody, AuthResponseCode

request = AuthRequestBody.from_json(payload)
decision = AuthResponseBody(auth_response_code=AuthResponseCode.APPROVED)

Module	Payload model(s)
enfuce_nextgen.issuer_events	CardEvent, CardholderEvent, TokenEvent
enfuce_nextgen.authorisation_control	AuthRequestBody → AuthResponseBody (synchronous decision)
enfuce_nextgen.threeds_oob	InitiateAuthenticationChallengeBody
enfuce_nextgen.transaction_event	TransactionEvent

A runnable FastAPI example of all of the above (both the API modules and the webhook receivers) lives in examples/backends/python.

File parsing

Enfuce delivers some data as a file rather than an HTTP API. These modules provide only the models — parse the file's JSON into them. clearing_file_copy is a clearing (settlement) file: a FileData header plus a list of records.

from enfuce_nextgen.clearing_file_copy import FileData

file = FileData.from_json(clearing_file_copy_json)
for record in file.records or []:
    ...

Module	Model(s)
enfuce_nextgen.clearing_file_copy	FileData (clearing file header + records)

Requirements

• Python >=3.9
• pydantic >=2

License

MIT