Skip to main content
Version: 2.0

Transaction lifecycle

A payment is a sequence of messages about one movement of funds. Fraudio stores each message as its own event. The field that joins those events is lifecycle_id.

Every event may carry a lifecycle_id. When you omit it, Fraudio uses that event's id, so the message stands as its own lifecycle. To attach a later message, set its lifecycle_id to the earlier event's id. You can also choose one payment id and send that same lifecycle_id on every message, including the first. Put a new event.id on every message either way. The payload key names the kind of message, for example card_network_transaction, bank_transfer, or dispute.

Score the message that needs a synchronous recommendation on Financial Events Screening. Send later messages on Financial Events Enrichment. Screening carries the value at event.lifecycle_id. Enrichment carries it at events[].lifecycle_id. v1 parenttransactionid is replaced by this shared value.

FieldWhat it identifies
event.idThis message only. Required, and unique for every event you send.
event.lifecycle_idThe payment. Optional. When omitted, Fraudio uses this event's id. Related messages repeat one value.

Some event types also carry their own ids, such as a card-network RRN or a payer narrative. Those ids do not replace lifecycle_id. The examples show where each one sits.

Examples​

Each row is a separate API call.

Regular card payment​

One purchase, lifecycle_id pay-100. Every row is a card_network_transaction.

MessageEndpointevent.idlifecycle_idtransaction_typerrnWhat else identifies it
Authorization requestScreeningauth-001pay-100purchase123456789012mti: "0100"
Authorization responseEnrichmentauth-resp-001pay-100purchase123456789012mti: "0110"
CaptureEnrichmentcap-001pay-100purchase210987654321mti: "0200"
Reversal of the captureEnrichmentrev-001pay-100purchase210987654321mti: "0400" or "0420"
RefundScreening or Enrichmentref-001pay-100refund654321098765

A follow-up authorization for the same purchase, such as an incremental authorization or a completion after an estimate, is another event with lifecycle_id pay-100 and a new event.id.

Important to note
  • lifecycle_id groups every related event in the purchase, including the capture, a reversal, and the refund. The value stays pay-100 whatever RRN each message carries.
  • rrn is the Retrieval Reference Number (ISO 8583 DE037) of that one message. It can differ across the authorization, the capture, the reversal, and the refund. In this example the authorization and its response use 123456789012, the capture uses 210987654321, and the refund uses 654321098765. A reversal repeats the RRN of the message it reverses, so the reversal of this capture uses 210987654321.
  • The reversal row reverses the capture. This example is not a partial reversal. A full reversal of the authorization is sent in place of the capture and cancels the authorization. The capture does not follow that reversal. The reversal still uses lifecycle_id pay-100.
  • Send the refund to Screening when it needs a score, and to Enrichment when it does not.

Recurring card payments​

Each billing cycle is its own payment, with its own lifecycle_id. recurring_lifecycle_id is the lifecycle_id of the first cycle. In this example that id is pay-r1, and every cycle repeats it. When recurring_lifecycle_id equals lifecycle_id, the message is the initial recurring transaction. Set recurring to true on the series.

CycleMessageEndpointevent.idlifecycle_idrecurring_lifecycle_idrecurring
1stAuthorization requestScreeningauth-r1pay-r1pay-r1true
1stCaptureEnrichmentcap-r1pay-r1pay-r1true
2ndAuthorization requestScreeningauth-r2pay-r2pay-r1true
2ndCaptureEnrichmentcap-r2pay-r2pay-r1true

lifecycle_id groups the messages of one cycle. recurring_lifecycle_id groups the cycles of one subscription. On the first cycle the two ids are equal. A dispute on the later cycle uses pay-r2.

Dispute on a card payment​

A dispute is another message in the payment it refers to. It uses that payment's lifecycle_id. The authorization request below is that payment. Every dispute event carries the same pay-100.

MessageEndpointevent.idlifecycle_idWhat else identifies it
Authorization requestScreeningauth-001pay-100mti: "0100", transaction_type: "purchase"
Visa fraud reportEnrichmentdsp-001pay-100dispute_type: "tc40"
First chargebackEnrichmentdsp-002pay-100dispute_type: "chargeback", dispute_stage: "1st_chargeback"
Pre-arbitrationEnrichmentdsp-003pay-100dispute_type: "chargeback", dispute_stage: "pre_arbitration"

dispute_type names the source: tc40 (Visa fraud report), safe (Mastercard fraud report), or chargeback. A TC40 typically arrives before the chargeback. Each stage is a new event with a new event.id and a new dispute_stage. A dispute is an event about the payment. When that dispute is declined, the payment's lifecycle status returns to purchased.

The dispute payload can be thinner than the original transaction. Include sender, receiver, amount, and reason fields when you have them.

Bank transfer​

Two account-to-account transfers. Every row is a bank_transfer. The first is accepted, settles, and is then returned. The second transfer is rejected. The same shape applies to wallet_transfer and wallet_payment.

MessageEndpointevent.idlifecycle_idstatus
Transfer initiationScreeningbt-001bt-100pending
AcceptanceEnrichmentbt-002bt-100accepted
SettlementEnrichmentbt-003bt-100completed
ReturnEnrichmentbt-004bt-100returned
Transfer initiationScreeningbt-101bt-200pending
RejectionEnrichmentbt-102bt-200rejected

The status values are described on bank_transfer.

Acceptance, settlement, return, and rejection are later statuses of the transfer. Each one is its own event, with the same lifecycle_id and a new event.id. Those events can omit sender, receiver, amount, currency, and rail when the initiation already sent them. payment_reference is the payer's narrative. It does not join the messages.