Events and identity

V3 records what happened when your organisation attempted a payment. It accepts observed destinations, switches and NIBSS technology without requiring Teria to own your routing configuration.

Release status: Use V3 to submit individual attempt outcomes or batches of telemetry from your institution.

Start with attempt outcomes

An outcome is the minimum useful telemetry. There is no requirement to send a preceding transaction_received or attempt_started event.

Kind	Meaning
`attempt_succeeded`	The attempt was reported successful.
`attempt_failed`	The attempt was reported failed.
`attempt_timed_out`	The attempt timed out; a later result may follow.
`attempt_reversed`	The attempt was reported reversed.
`attempt_started`	Optional observation that an attempt began.
`transaction_received`	Optional observation before a switch or attempt is known.

An attempt event includes event_id, transaction_id, attempt_id, connected_institution_id, destination_institution_id, payment_capability, switch_id, kind and occurred_at. Use interbank_transfer as the payment capability. If switch_id is nibss, include nibss_technology as nip or nps. Other switch events omit that field.

A transaction_received event includes the same transaction and institution information but omits attempt ID, switch and NIBSS technology. The API reference defines the exact fields and limits for each event shape.

Keep three identities distinct

Identifier	When to reuse it
`transaction_id`	Across attempts belonging to the same logical transaction.
`attempt_id`	Across observations of one actual payment attempt. A payment retry uses a new attempt ID.
`event_id`	Only when redelivering exactly the same observation. Generate a new UUID for a later observation.

For example, an attempt can first time out and later succeed. Send two event IDs with the same transaction and attempt IDs, each with its own occurrence time. If the successful attempt is later reversed, send a third observation. Do not rewrite the earlier timeout or success.

Teria reconstructs observations by occurrence time and retains receipt time. Delayed events update the historical period in which they occurred. Ambiguous contradictory observations are retained for investigation. Outcomes alone do not establish the final status of a transaction with potentially several attempts.

Optional measurements

Include latency_ms only when measured. Omit missing measurements rather than sending an estimated zero. response_code may carry a non-personal switch response code.

Provide amount_minor and currency together, or omit both. The amount is a non-negative integer in minor currency units, within the range documented in the schema; currency is a three-letter uppercase code. For NGN, for example, 10000 minor units represents NGN 100.00.

Only documented fields are accepted. Use opaque references, and exclude names, account numbers, email addresses and payment descriptions.

Directory identifiers

Use the enabled destination and switch identifiers supplied by Teria during onboarding. An institution name or bank code is not a substitute for destination_institution_id. Ask for the current directory mapping when adding a destination. Unknown or disabled identifiers cause validation errors.

The example-* identifiers in this documentation are synthetic and must be replaced before submitting. Do not copy another customer's organisation or institution identifiers.

Optional fuller tracking

The following illustrates transaction receipt, attempt start and outcome. Set the timestamps to the actual instants observed and generate new IDs for new observations.

{
  "schema_version": 3,
  "batch_id": "a343d973-6e69-4427-9171-b043e160587d",
  "organization_id": "example-organization",
  "environment": "sandbox",
  "sent_at": "2026-10-22T12:00:00.000Z",
  "events": [
    {
      "event_id": "2351a641-1ce5-48db-bc43-dab2fc4dddb8",
      "transaction_id": "example-transaction-001",
      "connected_institution_id": "example-institution",
      "destination_institution_id": "example-destination",
      "payment_capability": "interbank_transfer",
      "occurred_at": "2026-10-22T12:00:00.000Z",
      "kind": "transaction_received"
    },
    {
      "event_id": "0934561f-b08a-4357-bec1-9bb185a326c3",
      "transaction_id": "example-transaction-001",
      "attempt_id": "example-attempt-001",
      "connected_institution_id": "example-institution",
      "destination_institution_id": "example-destination",
      "payment_capability": "interbank_transfer",
      "switch_id": "nibss",
      "nibss_technology": "nip",
      "occurred_at": "2026-10-22T12:00:00.000Z",
      "kind": "attempt_started"
    },
    {
      "event_id": "349698d3-e52b-4c16-a3c3-33217146eb25",
      "transaction_id": "example-transaction-001",
      "attempt_id": "example-attempt-001",
      "connected_institution_id": "example-institution",
      "destination_institution_id": "example-destination",
      "payment_capability": "interbank_transfer",
      "switch_id": "nibss",
      "nibss_technology": "nip",
      "occurred_at": "2026-10-22T12:00:00.000Z",
      "kind": "attempt_succeeded",
      "latency_ms": 284
    }
  ]
}

Use one schema version per batch. V3 has schema_version: 3 at the batch level; its individual events do not carry schema_version or routing_config_version. See Versioning for V2 compatibility.

Explore the API reference →Sandbox · Schema V3