Skip to content

components.payment_gateway.public.entities

This module defines all the common entities that don't belong to a specific subcomponent. It also exports all the public entities from all the subcomponents.

Attributes

AccountHolderId module-attribute 

AccountHolderId = NewType('AccountHolderId', UUID)

AccountId module-attribute 

AccountId = NewType('AccountId', UUID)

AccountTransferId module-attribute 

AccountTransferId = NewType('AccountTransferId', UUID)

BankTransferId module-attribute 

BankTransferId = NewType('BankTransferId', UUID)

CardHolderId module-attribute 

CardHolderId = NewType('CardHolderId', UUID)

CardId module-attribute 

CardId = NewType('CardId', UUID)

CardProvisioningId module-attribute 

CardProvisioningId = NewType('CardProvisioningId', UUID)

CardTransferId module-attribute 

CardTransferId = NewType('CardTransferId', UUID)

ExpenseCategoryId module-attribute 

ExpenseCategoryId = NewType('ExpenseCategoryId', UUID)

ExpenseLimitRuleId module-attribute 

ExpenseLimitRuleId = NewType('ExpenseLimitRuleId', UUID)

InternalTransferId module-attribute 

InternalTransferId = NewType('InternalTransferId', UUID)

LedgerEntryId module-attribute 

LedgerEntryId = NewType('LedgerEntryId', UUID)

LedgerId module-attribute 

LedgerId = NewType('LedgerId', UUID)

LineOfCreditId module-attribute 

LineOfCreditId = NewType('LineOfCreditId', UUID)

OrganizationType module-attribute 

OrganizationType = Literal[
    "associationIncorporated",
    "governmentalOrganization",
    "listedPublicCompany",
    "nonProfit",
    "partnershipIncorporated",
    "privateCompany",
]

RuleCriterion module-attribute 

RuleCriterion = (
    CountryCriterion
    | ProcessingTypeCriterion
    | MCCCriterion
    | MerchantCriterion
    | CurrencyCriterion
)

Criterion to match against a payment.

All criteria must be met for a rule to apply.

The order of the criteria doesn't matter, however each type of criterion should be used at most once.

SepaBeneficiaryId module-attribute 

SepaBeneficiaryId = NewType('SepaBeneficiaryId', UUID)

SepaMandateId module-attribute 

SepaMandateId = NewType('SepaMandateId', UUID)

Transfer module-attribute 

Transfer = (
    CardTransfer
    | BankTransfer
    | AccountTransfer
    | InternalTransfer
)

TransferEventId module-attribute 

TransferEventId = NewType('TransferEventId', UUID)

TransferHistoryId module-attribute 

TransferHistoryId = NewType('TransferHistoryId', UUID)

TransferId module-attribute 

TransferId = (
    CardTransferId
    | BankTransferId
    | AccountTransferId
    | InternalTransferId
)

TransferUpdateId module-attribute 

TransferUpdateId = NewType('TransferUpdateId', UUID)

UsageRestrictionRuleId module-attribute 

UsageRestrictionRuleId = NewType(
    "UsageRestrictionRuleId", UUID
)

Classes

Account dataclass 

Account(
    id,
    account_holder_id,
    description,
    reference,
    status,
    external_id,
)

Account entity.

Attributes

account_holder_id instance-attribute 
account_holder_id
description instance-attribute 
description
external_id instance-attribute 
external_id

Opaque identifier of the account in the payment service provider.

id instance-attribute 
id
reference instance-attribute 
reference
status instance-attribute 
status

AccountHolder dataclass 

AccountHolder(id, description, external_id, reference)

Entity owning an account.

Attributes

description instance-attribute 
description
external_id instance-attribute 
external_id
id instance-attribute 
id
reference instance-attribute 
reference

AccountTransfer dataclass 

AccountTransfer(
    id,
    direction,
    reference,
    effective_date,
    account_id,
    transfer_history_id,
    updates,
    events,
    raw,
)

Attributes

account_id instance-attribute 
account_id
direction instance-attribute 
direction
effective_date instance-attribute 
effective_date
events instance-attribute 
events
id instance-attribute 
id
raw instance-attribute 
raw
reference instance-attribute 
reference
transfer_history_id instance-attribute 
transfer_history_id
updates instance-attribute 
updates

BalanceInformation dataclass 

BalanceInformation(received, reserved, balance)

Attributes

balance instance-attribute 
balance
received instance-attribute 
received
reserved instance-attribute 
reserved

BankTransfer dataclass 

BankTransfer(
    id,
    external_id,
    direction,
    effective_date,
    account_id,
    transfer_history_id,
    updates,
    events,
    sepa_mandate_id,
    sepa_beneficiary_id,
    raw,
)

Attributes

account_id instance-attribute 
account_id
direction instance-attribute 
direction
effective_date instance-attribute 
effective_date
events instance-attribute 
events
external_id instance-attribute 
external_id
id instance-attribute 
id
raw instance-attribute 
raw
sepa_beneficiary_id instance-attribute 
sepa_beneficiary_id
sepa_mandate_id instance-attribute 
sepa_mandate_id
transfer_history_id instance-attribute 
transfer_history_id
updates instance-attribute 
updates

BankTransferAccount dataclass 

BankTransferAccount(
    bank_transfer_account_id,
    bank_transfer_account_info,
    bank_transfer_account_type,
)

Represents a bank account to which a bank transfer can be made (ex: BankAccountInfo in Canada).

Attributes

bank_transfer_account_id instance-attribute 
bank_transfer_account_id
bank_transfer_account_info instance-attribute 
bank_transfer_account_info
bank_transfer_account_type instance-attribute 
bank_transfer_account_type

Card dataclass 

Card(
    id,
    card_holder_id,
    account_id,
    form_factor,
    display_name,
    expiration_year,
    expiration_month,
    last_four_digits,
    status,
    external_id,
    description,
    reference,
    issued_at=isodatetime_field(),
    issuance_reason=None,
    suspension_source=None,
)

Card entity.

Attributes

account_id instance-attribute 
account_id
card_holder_id instance-attribute 
card_holder_id
description instance-attribute 
description
display_name instance-attribute 
display_name
expiration_month instance-attribute 
expiration_month
expiration_year instance-attribute 
expiration_year
external_id instance-attribute 
external_id

Opaque identifier of the card in the payment service provider.

form_factor instance-attribute 
form_factor
id instance-attribute 
id
issuance_reason class-attribute instance-attribute 
issuance_reason = None

Reason for issuing the card.

issued_at class-attribute instance-attribute 
issued_at = isodatetime_field()

Date and time when the card was issued.

last_four_digits instance-attribute 
last_four_digits
reference instance-attribute 
reference
status instance-attribute 
status
suspension_source class-attribute instance-attribute 
suspension_source = None

Who initiated the suspension of the card.

CardHolder dataclass 

CardHolder(
    id,
    provider,
    external_id,
    first_name,
    last_name,
    display_name=None,
    short_name=None,
)

Person owning a card.

Attributes

display_name class-attribute instance-attribute 
display_name = None
external_id instance-attribute 
external_id
first_name instance-attribute 
first_name
id instance-attribute 
id
last_name instance-attribute 
last_name
provider instance-attribute 
provider
short_name class-attribute instance-attribute 
short_name = None

CardIssuingConfiguration dataclass 

CardIssuingConfiguration(
    country_code, brand, brand_variant, profile_id
)

Card issuing configuration for the payment service provider.

Attributes

brand instance-attribute 
brand
brand_variant instance-attribute 
brand_variant
country_code instance-attribute 
country_code
profile_id instance-attribute 
profile_id

CardOrder dataclass 

CardOrder(
    card_id,
    delivery_status,
    shipping_method,
    tracking_number=None,
)

Card order entity.

Attributes

card_id instance-attribute 
card_id
delivery_status instance-attribute 
delivery_status
shipping_method instance-attribute 
shipping_method

shipping method, known at order creation time.

tracking_number class-attribute instance-attribute 
tracking_number = None

Tracking number provided by the shipping service, known at shipping time.

CardPaymentMerchant dataclass 

CardPaymentMerchant(
    merchant_id, name, mcc, postal_code, city, country_code
)

Attributes

city instance-attribute 
city
country_code instance-attribute 
country_code

ISO 3166-1 alpha-3 country code

mcc instance-attribute 
mcc
merchant_id instance-attribute 
merchant_id
name instance-attribute 
name
postal_code instance-attribute 
postal_code

CardProvisioning dataclass 

CardProvisioning(
    id,
    card_id,
    external_id,
    provisioning_type,
    provisioning_date,
    wallet_provider,
    provider,
)

CardProvisioning entity

Attributes

card_id instance-attribute 
card_id
external_id instance-attribute 
external_id
id instance-attribute 
id
provider instance-attribute 
provider
provisioning_date instance-attribute 
provisioning_date
provisioning_type instance-attribute 
provisioning_type
wallet_provider instance-attribute 
wallet_provider

CardRevealPANData dataclass 

CardRevealPANData(encrypted_data)

Bases: DataClassJsonMixin

Encrypted card PAN reveal data.

Attributes

encrypted_data instance-attribute 
encrypted_data

Hex-encoded encrypted PAN data

CardRevealPINData dataclass 

CardRevealPINData(encrypted_pin_block, token)

Bases: DataClassJsonMixin

Encrypted card PIN reveal data.

Attributes

encrypted_pin_block instance-attribute 
encrypted_pin_block

Hex-encoded encrypted PIN block data

token instance-attribute 
token

Token used for extraction of the PIN from the PIN block

CardShipmentInfo dataclass 

CardShipmentInfo(
    first_name,
    last_name,
    address_line1,
    postal_code,
    city,
    country,
    phone_number=None,
    address_line2=None,
    state_or_province=None,
)

Name and address to which a physical card will be shipped.

Attributes

address_line1 instance-attribute 
address_line1
address_line2 class-attribute instance-attribute 
address_line2 = None
city instance-attribute 
city
country instance-attribute 
country
first_name instance-attribute 
first_name
last_name instance-attribute 
last_name
phone_number class-attribute instance-attribute 
phone_number = None
postal_code instance-attribute 
postal_code
state_or_province class-attribute instance-attribute 
state_or_province = None

CardTransfer dataclass 

CardTransfer(
    id,
    effective_date,
    merchant,
    card_id,
    account_id,
    updates,
    events,
    raw,
    transfer_history_id,
)

Attributes

account_id instance-attribute 
account_id
card_id instance-attribute 
card_id
effective_date instance-attribute 
effective_date
events instance-attribute 
events
id instance-attribute 
id
merchant instance-attribute 
merchant
raw instance-attribute 
raw
transfer_history_id instance-attribute 
transfer_history_id
updates instance-attribute 
updates

CountryCriterion dataclass 

CountryCriterion(
    condition, country_codes, _type="CountryCriterion"
)

Bases: DataClassJsonMixin

Matches payments based on the merchant country code.

Attributes

condition instance-attribute 
condition
country_codes instance-attribute 
country_codes

CurrencyCriterion dataclass 

CurrencyCriterion(same_as_card, _type='CurrencyCriterion')

Bases: DataClassJsonMixin

Matches payments against the card currency.

Attributes

same_as_card instance-attribute 
same_as_card

ExpenseLimitRule dataclass 

ExpenseLimitRule(
    id,
    card_id,
    description,
    reference,
    amount,
    currency,
    period,
    criteria,
    is_active,
    first_day,
    start,
    end,
    external_id,
)

Expense limit rule that applies on payments made with a card.

Expense limits set a limit on the total amount that can be spent with a card over a given period (day, month, ...). Once this limit is reached, the card can't be used anymore until the period ends.

Expense limits are immutable except for their amount once created, they can't be changed or deleted. However, they can be activated or deactivated at any time.

The amount can also be changed at any time, however this can have unexpected effects in the middle of a validity period (for example, monthly expense caps). It is best to change the amount outside at the beginning or end of a period or on an inactive one.

All criteria must be met for the rule to apply.

All active rules apply simultaneously on each payment made with the card. The order in which they are created doesn't matter. If a payment exceeds any active limit then it is blocked.

Attributes

amount instance-attribute 
amount
card_id instance-attribute 
card_id
criteria instance-attribute 
criteria
currency instance-attribute 
currency
description instance-attribute 
description
end instance-attribute 
end
external_id instance-attribute 
external_id

Opaque identifier of the rule in the payment service provider.

first_day instance-attribute 
first_day
id instance-attribute 
id
is_active instance-attribute 
is_active
period instance-attribute 
period
reference instance-attribute 
reference
start instance-attribute 
start

InternalTransfer dataclass 

InternalTransfer(
    id,
    effective_date,
    amount,
    description,
    reference,
    transfer_history_id,
)

Attributes

amount instance-attribute 
amount
description instance-attribute 
description
effective_date instance-attribute 
effective_date
id instance-attribute 
id
reference instance-attribute 
reference
transfer_history_id instance-attribute 
transfer_history_id

Ledger dataclass 

Ledger(balance, description, reference)

Attributes

balance instance-attribute 
balance
description instance-attribute 
description
reference instance-attribute 
reference

LedgerEntry dataclass 

LedgerEntry(
    ledger_id,
    opening_balance,
    amount,
    ending_balance,
    occurred_at,
    created_at,
    description,
    reference,
    metadata,
)

Attributes

amount instance-attribute 
amount
created_at instance-attribute 
created_at
description instance-attribute 
description
ending_balance instance-attribute 
ending_balance
ledger_id instance-attribute 
ledger_id
metadata instance-attribute 
metadata
occurred_at instance-attribute 
occurred_at
opening_balance instance-attribute 
opening_balance
reference instance-attribute 
reference

LegalEntityAddressParams dataclass 

LegalEntityAddressParams(
    city,
    country,
    postal_code,
    state_or_province,
    street,
    street2,
)

Represents the address of a legal entity.

Attributes

city instance-attribute 
city
country instance-attribute 
country
postal_code instance-attribute 
postal_code
state_or_province instance-attribute 
state_or_province
street instance-attribute 
street
street2 instance-attribute 
street2

LegalEntityOnboardResult dataclass 

LegalEntityOnboardResult(
    legal_entity_id, account_holder_id
)

Represents the result of onboarding a legal entity.

Attributes

account_holder_id instance-attribute 
account_holder_id
legal_entity_id instance-attribute 
legal_entity_id

MCCCriterion dataclass 

MCCCriterion(condition, mccs, _type='MCCCriterion')

Bases: DataClassJsonMixin

Matches payments based on the merchant category code.

Attributes

condition instance-attribute 
condition
mccs instance-attribute 
mccs

MerchantCriterion dataclass 

MerchantCriterion(
    condition, merchants, _type="MerchantCriterion"
)

Bases: DataClassJsonMixin

Matches payments based on the merchant identifiers.

Attributes

condition instance-attribute 
condition
merchants instance-attribute 
merchants

MerchantIdPair dataclass 

MerchantIdPair(acquirer_id, merchant_id)

Bases: DataClassJsonMixin

Merchant identifiers.

Attributes

acquirer_id instance-attribute 
acquirer_id
merchant_id instance-attribute 
merchant_id

MerchantInfo dataclass 

MerchantInfo(
    merchant_id,
    acquirer_id=None,
    mcc=None,
    name=None,
    postal_code=None,
    city=None,
    country=None,
)

Info about a merchant identified by its Merchant ID.

This is the (possibly incomplete) information we store about the merchant in our merchant registry. We try to keep it up-to-date with the information we receive from the PSP, using the Merchant ID as the key.

Note

Some fields may be None for various reasons: - They might not be relevant for the merchant (e.g. e-commerce platforms may not have a postal code) - They were missing from the events we received from the PSP, although we try to augment them as we go

Attributes

acquirer_id class-attribute instance-attribute 
acquirer_id = None

Provider-specific acquirer ID (Used by Adyen but not Swan)

city class-attribute instance-attribute 
city = None

City name

country class-attribute instance-attribute 
country = None

English country name

mcc class-attribute instance-attribute 
mcc = None

Merchant Category Code (MCC)

merchant_id instance-attribute 
merchant_id

Merchant ID (acquirer- and provider-specific)

name class-attribute instance-attribute 
name = None

Merchant name

postal_code class-attribute instance-attribute 
postal_code = None

Postal code

PendingTransaction dataclass 

PendingTransaction(
    amount,
    currency,
    card_id,
    merchant_info,
    provider,
    external_id,
)

Information about a transaction to be authorized.

Attributes

amount instance-attribute 
amount

Transaction amount (positive for debit, in minor units).

card_id instance-attribute 
card_id

Card used for the transaction.

currency instance-attribute 
currency

Currency used for the transaction.

external_id instance-attribute 
external_id

ID used by the external payment service provider to identify the transaction.

merchant_info instance-attribute 
merchant_info

Merchant information.

provider instance-attribute 
provider

Payment service provider that is processing the transaction.

PendingTransactionMerchantInfo dataclass 

PendingTransactionMerchantInfo(
    merchant_id,
    acquirer_id,
    mcc,
    name,
    country,
    postal_code=None,
    city=None,
)

Merchant information for a pending transaction.

Note

All fields are always present during authorization, those which are None might simply be irrelevant for the merchant (e.g. e-commerce platforms may not have a postal code)

Attributes

acquirer_id instance-attribute 
acquirer_id
city class-attribute instance-attribute 
city = None
country instance-attribute 
country

ISO 3166-1 alpha-3 country code of the merchant.

mcc instance-attribute 
mcc
merchant_id instance-attribute 
merchant_id
name instance-attribute 
name
postal_code class-attribute instance-attribute 
postal_code = None

ProcessingTypeCriterion dataclass 

ProcessingTypeCriterion(
    condition,
    processing_types,
    _type="ProcessingTypeCriterion",
)

Bases: DataClassJsonMixin

Matches payments based on the processing type.

Attributes

condition instance-attribute 
condition
processing_types instance-attribute 
processing_types

RecipientAddress dataclass 

RecipientAddress(street, postal_code, city, country)

Represents the address of a recipient (user or company).

Attributes

city instance-attribute 
city
country instance-attribute 
country
postal_code instance-attribute 
postal_code
street instance-attribute 
street

RecipientUser dataclass 

RecipientUser(profile_id, first_name, last_name, address)

Represents an individual recipient for a payout.

Attributes

address instance-attribute 
address
first_name instance-attribute 
first_name
last_name instance-attribute 
last_name
profile_id instance-attribute 
profile_id

SepaBeneficiary dataclass 

SepaBeneficiary(
    id,
    account_id,
    provider,
    external_id,
    name,
    iban,
    issued_at,
    status,
)

SEPA beneficiary entity.

Attributes

account_id instance-attribute 
account_id
external_id instance-attribute 
external_id
iban instance-attribute 
iban
id instance-attribute 
id
issued_at instance-attribute 
issued_at
name instance-attribute 
name
provider instance-attribute 
provider
status instance-attribute 
status

SepaMandate dataclass 

SepaMandate(
    id,
    provider,
    external_id,
    account_holder_id,
    sepa_creditor_identifier,
    unique_mandate_reference,
    debtor_name,
    debtor_iban,
    issued_at,
    status,
)

Attributes

account_holder_id instance-attribute 
account_holder_id
debtor_iban instance-attribute 
debtor_iban
debtor_name instance-attribute 
debtor_name
external_id instance-attribute 
external_id
id instance-attribute 
id
issued_at instance-attribute 
issued_at
provider instance-attribute 
provider
sepa_creditor_identifier instance-attribute 
sepa_creditor_identifier
status instance-attribute 
status
unique_mandate_reference instance-attribute 
unique_mandate_reference

TransferEvent dataclass 

TransferEvent(
    id,
    effective_date,
    received,
    reserved,
    balance,
    status,
    raw,
)

Attributes

balance instance-attribute 
balance
effective_date instance-attribute 
effective_date
id instance-attribute 
id
raw instance-attribute 
raw
received instance-attribute 
received
reserved instance-attribute 
reserved
status instance-attribute 
status

TransferRulesEvaluation dataclass 

TransferRulesEvaluation(score, failed_rules)

Attributes

failed_rules instance-attribute 
failed_rules
score instance-attribute 
score

TransferTransactionRule dataclass 

TransferTransactionRule(id, reason, description)

Attributes

description instance-attribute 
description
id instance-attribute 
id
reason instance-attribute 
reason

TransferUpdate dataclass 

TransferUpdate(
    id,
    transfer_id,
    transfer_type,
    direction,
    sequence_number,
    occurred_at,
    amount,
    currency,
    status,
    provider,
    external_transaction_id=None,
    external_transfer_id=None,
    raw=None,
)

Attributes

amount instance-attribute 
amount
currency instance-attribute 
currency
direction instance-attribute 
direction
external_transaction_id class-attribute instance-attribute 
external_transaction_id = None
external_transfer_id class-attribute instance-attribute 
external_transfer_id = None
id instance-attribute 
id
occurred_at instance-attribute 
occurred_at
provider instance-attribute 
provider
raw class-attribute instance-attribute 
raw = None
sequence_number instance-attribute 
sequence_number
status instance-attribute 
status
transfer_id instance-attribute 
transfer_id
transfer_type instance-attribute 
transfer_type

UsageRestrictionRule dataclass 

UsageRestrictionRule(
    id,
    account_id,
    description,
    reference,
    criteria,
    is_active,
    start,
    end,
    external_id,
)

Usage restriction rule that applies on payments made with any card linked to an account.

Usage restrictions are immutable; once created, they can't be changed or deleted. However, they can be activated or deactivated at any time.

All criteria must be met for the rule to apply.

All active rules apply simultaneously on each payment made with a card linked to the account. The order in which they are created doesn't matter. If a payment matches any active rule then it is blocked.

Attributes

account_id instance-attribute 
account_id
criteria instance-attribute 
criteria
description instance-attribute 
description
end instance-attribute 
end
external_id instance-attribute 
external_id

Opaque identifier of the rule in the payment service provider.

id instance-attribute 
id
is_active instance-attribute 
is_active
reference instance-attribute 
reference
start instance-attribute 
start

WebhookLog dataclass 

WebhookLog(id, payload)

Bases: DataClassJsonMixin

Attributes

id instance-attribute 
id
payload instance-attribute 
payload

WebhookLogExtended dataclass 

WebhookLogExtended(
    id,
    payload,
    transfer_id,
    transfer_external_id,
    transfer_status,
    transfer_type,
    account_id,
    account_external_id,
    payment_instrument_external_id,
    card_holder_id,
    amount,
    payment_date,
    history,
    rules,
)

Bases: WebhookLog

This class extends the WebhookLog class with additional fields that are not present in the WebhookLog class.

It is used to represent the webhook log with additional fields to easily access important informations to be used in the business logic.

Attributes

account_external_id instance-attribute 
account_external_id
account_id instance-attribute 
account_id
amount instance-attribute 
amount
card_holder_id instance-attribute 
card_holder_id
history instance-attribute 
history
payment_date instance-attribute 
payment_date
payment_instrument_external_id instance-attribute 
payment_instrument_external_id
rules instance-attribute 
rules
transfer_external_id instance-attribute 
transfer_external_id
transfer_id instance-attribute 
transfer_id
transfer_status instance-attribute 
transfer_status
transfer_type instance-attribute 
transfer_type

WebhookLogTransferEvent dataclass 

WebhookLogTransferEvent(timestamp, status, event, payload)

Attributes

event instance-attribute 
event
payload instance-attribute 
payload
status instance-attribute 
status
timestamp instance-attribute 
timestamp