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.
| Field | What it identifies |
|---|---|
event.id | This message only. Required, and unique for every event you send. |
event.lifecycle_id | The 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.
| Message | Endpoint | event.id | lifecycle_id | transaction_type | rrn | What else identifies it |
|---|---|---|---|---|---|---|
| Authorization request | Screening | auth-001 | pay-100 | purchase | 123456789012 | mti: "0100" |
| Authorization response | Enrichment | auth-resp-001 | pay-100 | purchase | 123456789012 | mti: "0110" |
| Capture | Enrichment | cap-001 | pay-100 | purchase | 210987654321 | mti: "0200" |
| Reversal of the capture | Enrichment | rev-001 | pay-100 | purchase | 210987654321 | mti: "0400" or "0420" |
| Refund | Screening or Enrichment | ref-001 | pay-100 | refund | 654321098765 |
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.
lifecycle_idgroups every related event in the purchase, including the capture, a reversal, and the refund. The value stayspay-100whatever RRN each message carries.rrnis 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 use123456789012, the capture uses210987654321, and the refund uses654321098765. A reversal repeats the RRN of the message it reverses, so the reversal of this capture uses210987654321.- 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_idpay-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.
| Cycle | Message | Endpoint | event.id | lifecycle_id | recurring_lifecycle_id | recurring |
|---|---|---|---|---|---|---|
| 1st | Authorization request | Screening | auth-r1 | pay-r1 | pay-r1 | true |
| 1st | Capture | Enrichment | cap-r1 | pay-r1 | pay-r1 | true |
| 2nd | Authorization request | Screening | auth-r2 | pay-r2 | pay-r1 | true |
| 2nd | Capture | Enrichment | cap-r2 | pay-r2 | pay-r1 | true |
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.
| Message | Endpoint | event.id | lifecycle_id | What else identifies it |
|---|---|---|---|---|
| Authorization request | Screening | auth-001 | pay-100 | mti: "0100", transaction_type: "purchase" |
| Visa fraud report | Enrichment | dsp-001 | pay-100 | dispute_type: "tc40" |
| First chargeback | Enrichment | dsp-002 | pay-100 | dispute_type: "chargeback", dispute_stage: "1st_chargeback" |
| Pre-arbitration | Enrichment | dsp-003 | pay-100 | dispute_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.
| Message | Endpoint | event.id | lifecycle_id | status |
|---|---|---|---|---|
| Transfer initiation | Screening | bt-001 | bt-100 | pending |
| Acceptance | Enrichment | bt-002 | bt-100 | accepted |
| Settlement | Enrichment | bt-003 | bt-100 | completed |
| Return | Enrichment | bt-004 | bt-100 | returned |
| Transfer initiation | Screening | bt-101 | bt-200 | pending |
| Rejection | Enrichment | bt-102 | bt-200 | rejected |
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.