Events
Events¶
These events are published through the events pipeline on
the PAYMENT_REQUEST_EVENT_STREAM ("stream:payment_gateway:payment_request_events").
The stream contains events for all countries. Each consumer is responsible for filtering
events relevant to its context (typically by checking account_id in the payload).
Messages¶
__all__
module-attribute
¶
PaymentRequestCreated
dataclass
¶
PaymentRequestCreated(
occurred_at,
workspace_key,
payment_request_id,
account_id,
bank_transfer_id,
transfer_update_id,
reference,
status,
)
PaymentRequestRefunded
dataclass
¶
PaymentRequestRefunded(
occurred_at,
workspace_key,
payment_request_id,
account_id,
bank_transfer_id,
reference,
failure_reason_code=None,
)
PaymentRequestUpdated
dataclass
¶
PaymentRequestUpdated(
occurred_at,
workspace_key,
payment_request_id,
account_id,
bank_transfer_id,
transfer_update_id,
reference,
status,
failure_reason_code=None,
failure_status=None,
)
Payment Request Statuses¶
Bases: AlanBaseEnum
Status of a payout bank transfer.
PaymentRequestStatus is the value carried by the status field of the
PaymentRequestCreated and PaymentRequestUpdated messages. The diagram below
describes the transitions consumers can expect to observe on the stream.
stateDiagram-v2
[*] --> submitted: submit succeeds
[*] --> submission_failed: submit rejected synchronously
submitted --> pending: PSP ack, not yet settled
submitted --> succeeded: PSP completed
submitted --> failed: PSP declined / failed / reverted
pending --> succeeded
pending --> failed
succeeded --> [*]
failed --> [*]
submission_failed --> [*]
note right of succeeded
A refund does NOT change PaymentRequestStatus.
It is surfaced as a separate
PaymentRequestRefunded event on the same stream.
end noteTerminal states. succeeded, failed, and submission_failed are terminal
for a given payment request.
Refunds
A succeeded payment request can later be refunded. A refund does not
change PaymentRequestStatus — it is surfaced as a separate
PaymentRequestRefunded event on the same stream.
Subscribing to Events¶
Use the @stream_consumer decorator to subscribe to the payment request event stream:
from components.events_pipeline.internal.consumer.event import StreamEvent
from components.events_pipeline.public.consumer import stream_consumer
from components.payment_gateway.public.events.event_streams import (
PAYMENT_REQUEST_EVENT_STREAM,
)
from components.payment_gateway.public.messages import (
PaymentRequestCreated,
PaymentRequestRefunded,
PaymentRequestUpdated,
)
@stream_consumer(PAYMENT_REQUEST_EVENT_STREAM, name="my_component_handle_payment_event")
def handle_payment_request_event(event: StreamEvent, session: Session) -> None:
"""Process Payment Gateway events."""
match event.event_type:
case "PaymentRequestCreated":
message = PaymentRequestCreated.from_json(event.payload)
# handle created ...
case "PaymentRequestUpdated":
message = PaymentRequestUpdated.from_json(event.payload)
# handle updated ...
case "PaymentRequestRefunded":
message = PaymentRequestRefunded.from_json(event.payload)
# handle refunded ...
The consumer receives a StreamEvent with:
- event.event_type — the event class name (e.g. "PaymentRequestCreated")
- event.payload — JSON string, deserializable via Message.from_json(event.payload)
The session is managed by the events pipeline worker (exactly-once delivery). Do not commit manually — the worker owns the transaction.