API Reference¶
Automatically generated documentation from the source code.
Client¶
eupago.EupagoClient
¶
__init__(api_key, *, client_id=None, client_secret=None, management_bearer=None, webhook_secret=None, sandbox=False, timeout=DEFAULT_TIMEOUT, max_retries=DEFAULT_MAX_RETRIES)
¶
:param management_bearer: pre-obtained Bearer token for /api/management/*.
Overrides client_id/client_secret when set. Intended for tests
or one-off scripts where the caller already has a token (e.g. from the
backoffice login flow); production callers should prefer OAuth via
client_id/client_secret.
Models¶
PaymentResult¶
eupago.models.PaymentResult
¶
Bases: BaseModel
PaymentStatus¶
eupago.models.PaymentStatus
¶
Bases: str, Enum
Customer¶
eupago.models.Customer
¶
Bases: BaseModel
WebhookEvent¶
eupago.models.WebhookEvent
¶
Bases: BaseModel
Exceptions¶
eupago.exceptions
¶
Services¶
Each service is reached via a property on the client (client.mbway,
client.multibanco, …). You don't import or instantiate them directly.
MBWayService¶
eupago.services.MBWayService
¶
Bases: BaseService
MultibancoService¶
eupago.services.MultibancoService
¶
Bases: BaseService
CreditCardService¶
eupago.services.CreditCardService
¶
Bases: BaseService
Credit card payments (3D-Secure flow).
The create/authorize/subscription endpoints return a redirectUrl —
the merchant redirects the customer there to enter the card details and
complete the 3D-Secure / OTP challenge on eupago's hosted page. The
final outcome arrives by webhook.
All payment endpoints require three return URLs (success_url,
error_url, back_url); without all three the API rejects with
URL_INVALID / URL_MISSING.
Sandbox test card: 4018810000150015 (Visa) — OTP 0101 succeeds,
3333 fails. Transactions above 500 EUR trigger the OTP prompt.
list_subscriptions()
¶
List every subscription on the channel.
Each row carries reference (public), identifier (merchant id),
eupagoToken (the hex passed to :meth:charge_subscription as
recurrent_id), status, payment, creationDate and
service. The integer subscriptionId used by
:meth:get_subscription / :meth:edit_subscription /
:meth:revoke_subscription is not in the list response — you
have to read it from the backoffice URL or by enumerating.
get_subscription(subscription_id)
¶
Fetch one subscription. subscription_id is the integer
identifier from the backoffice URL (NOT the eupagoToken).
edit_subscription(subscription_id, *, collection_day=None, auto_process=None)
¶
Edit billing options on a registered subscription.
collection_day: 1..28, day of month eupago bills.auto_process:Trueto let eupago bill automatically oncollection_dayof each period;Falseto require explicit :meth:charge_subscriptioncalls.
Eupago recomputes nextCollectionDate server-side.
revoke_subscription(subscription_id)
¶
Cancel an active subscription. Returns the eupago response.
Only valid for subscriptions in an active state (not Pendente):
the API returns SUBSCRIPTION_NOT_FOUND otherwise.
ApplePayService¶
eupago.services.ApplePayService
¶
Bases: BaseService
Apple Pay payments.
The wallet returns a PKPaymentToken after the user authenticates
(Touch ID / Face ID). The caller forwards that token (typically as a
JSON string or base64 payload, depending on Apple's wallet
configuration) to apple_pay_token; eupago decrypts it server-side
and processes the card payment.
Unit-tested only — full live verification requires a real device with
an Apple Wallet card. Body shape mirrors the verified credit-card v1.02
contract; the applePayToken field name follows eupago's naming
convention.
GooglePayService¶
eupago.services.GooglePayService
¶
Bases: BaseService
Google Pay payments.
Google Pay returns a PaymentData JSON after the user picks a card.
The caller forwards the encoded token to google_pay_token; eupago
decrypts it server-side and processes the card payment.
Unit-tested only — full live verification requires a real device with Google Pay enabled and the merchant configured in the Google Pay API console. Body shape mirrors the verified credit-card v1.02 contract.
PayByLinkService¶
eupago.services.PayByLinkService
¶
Bases: BaseService
Pay By Link — eupago-hosted checkout page.
Generate a single URL the customer opens to choose how to pay (MB WAY, Multibanco, Card, Apple/Google Pay, Cofidis, …). No checkout/website is needed on your side. Best suited to invoices, social-commerce flows, B2B billing, or anywhere the customer picks the method.
The response carries the payment_url (the customer-facing link) and a
transaction_id. The final outcome arrives via the standard payment
webhook once the customer completes the flow on eupago's page.
RefundService¶
eupago.services.RefundService
¶
Bases: BaseService
Refunds via the management API.
Requires OAuth credentials (client_id + client_secret on the
EupagoClient). The same secret pair gates every /api/management/...
endpoint.
Getting the OAuth credentials: these are NOT the API key and are not
self-service in the backoffice. As of writing, eupago issues
client_id / client_secret on request via their support portal
(customer.support.eupago.com <https://customer.support.eupago.com>_).
The /api/auth/token endpoint accepts grant_type=client_credentials
(preferred) or grant_type=password (with the backoffice
username/password) — both still require the client_id / client_secret
pair.
Refund webhooks: the eupago documentation says no webhook fires for
refunds. In practice it does (confirmed live in production,
2026-05-31): an async webhook arrives with method="RB:PT",
status="REFUNDED", and an originalTrid field pointing back at the
original payment's transaction_id. The SDK normalizes these via
client.webhooks.parse(...) →
WebhookEvent(method="refund", status=REFUNDED, original_transaction_id=…).
The synchronous response is still authoritative (200/201 + refundId),
but the webhook is useful for reconciliation back to the original payment.
get(refund_id)
¶
Fetch the current state of a refund (e.g. for Multibanco refunds,
which settle asynchronously — the sync response is "Pendente" and
the actual bank-to-bank clearing happens later).
Returns the refundList dict from the eupago response, with at
least identifier, reference and status. Verified live in
production 2026-05-31.