Send your first sandbox outcome

Send test observations of payments handled by your institution. Your organisation continues to choose switches and execute payments. Teria receives telemetry to help you understand attempt outcomes and route health.

Before you begin

Ask your Teria administrator to activate your institution's sandbox telemetry access. You will receive your organisation ID, connected institution ID, enabled destination and switch identifiers, and an institution-specific integration guide. The credential secret is delivered separately and shown only once when issued.

Each credential authorizes one institution in one organisation and environment. If your organisation integrates several institutions centrally, submit a separate batch with the matching credential for each institution.

Use synthetic payment references and test data. Exclude names, email addresses, account numbers and payment descriptions.

Verify your credential with GET /v1/telemetry/connection before sending outcomes. The response confirms the authorised organisation, institution and environment. See Authentication for the request and response format.

1. Prepare an outcome

A single completed attempt is enough to start. Save the following as outcome.json and replace example-organization, example-institution and example-destination with your onboarding identifiers. Use the switch and NIBSS technology actually observed. Set sent_at and occurred_at to appropriate current timestamps; the timestamps below are illustrative.

Generate a fresh batch_id and event_id for your first test. Keep the event ID, occurrence time and remaining event content unchanged when retrying it.

{
  "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": "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
    }
  ]
}

The events array supports one to 1,000 events. There is no separate endpoint for individual outcomes. A new payment attempt gets a new attempt_id; a later observation of the same attempt gets a new event_id.

2. Submit securely

Set TERIA_INGESTION_CREDENTIAL securely in your local environment to the complete credential_id.secret value. Keep it out of source control and shell history. Then send your prepared file:

curl --request POST \
  --url https://sandbox.teriahq.com/v1/telemetry/batches \
  --header "Authorization: Bearer $TERIA_INGESTION_CREDENTIAL" \
  --header "Content-Type: application/json" \
  --data-binary @outcome.json

The sandbox endpoint is https://sandbox.teriahq.com/v1/telemetry/batches. Sandbox credentials and data are separate from production.

3. Confirm acceptance and processing

202 Accepted means the events have been durably accepted for asynchronous processing. It does not establish that the outcome has already appeared in your workspace. Save the returned request_id for troubleshooting and inspect accepted_event_count and duplicate_event_count.

Confirm your first processed outcome in your institution's integration status with your Teria administrator. The milestones are credential issued, connection verified, first batch accepted, and first outcome processed. Connection verification alone does not complete onboarding.

4. Retry the same observation

Submit the same file again. The outcome should be counted as a duplicate, with no additional attempt created. Do not generate a new event ID just because the network timed out or a response was lost.

For an outage test, keep the immutable events in a durable local buffer and deliver them after connectivity returns. Read Reliable delivery before connecting your continuous event feed.

Tools and next steps

• Explore the API reference, including field definitions and responses.
• Download the OpenAPI 3.1 definition.
• Import the Postman collection and empty sandbox environment. Add credentials only in your private environment.
• Read Authentication, Events and the Sandbox testing checklist.

The Postman collection creates fresh timestamps and IDs on first use, then preserves that payload across retries. Clear its stored payload variable only when deliberately creating a new test observation. The documentation reference does not store your credential or send requests through a documentation proxy.