Developer Guide

Integration reference for developers building applications on top of OMNYTH.

Integration Lifecycle

Integrating with OMNYTH follows four stages:

Configure — set up country profiles, payment types, rails, and flow definitions in the OMNYTH platform.
Test — submit test payments through the Experience API against your configured flows.
Validate — review step-level execution logs to confirm routing, compliance, and provider selection behave as expected.
Go Live — switch to production credentials and publish your flows.

Authentication

OMNYTH uses token-based authentication. All API requests must include a bearer token obtained from the authentication server. Tokens are scoped to a specific realm and expire after a configurable period.

Contact your OMNYTH administrator to obtain client credentials for your integration. Do not hardcode credentials in application source code.

Experience APIs

The Experience API is the integration entry point. It provides a versioned, clean interface for initiating payments, checking status, and handling responses — without requiring knowledge of internal flow or provider structure.

Experience APIs are defined in the OMNYTH platform and expose exactly the fields your application needs. Sensitive fields are masked in responses. Internal routing and provider details are not exposed.

Request Structure

A payment initiation request contains:

{
  "payment_type": "DOMESTIC_TRANSFER",
  "source_country": "JO",
  "currency": "JOD",
  "amount": 500.00,
  "debtor": {
    "account_number": "...",
    "bank_code": "..."
  },
  "creditor": {
    "account_number": "...",
    "bank_code": "..."
  },
  "reference": "INV-2026-001",
  "metadata": {}
}

Response Structure

Successful initiation response:

{
  "payment_id": "PAY-20260604-00001",
  "status": "RECEIVED",
  "created_at": "2026-06-04T10:00:00Z",
  "reference": "INV-2026-001"
}

Failure response:

{
  "error": "VALIDATION_FAILED",
  "message": "Amount exceeds daily limit for this payment type",
  "payment_id": "PAY-20260604-00002",
  "status": "FAILED"
}

Error Model

Error Code	Meaning	Retryable
`VALIDATION_FAILED`	Request fields failed validation	No
`LIMIT_EXCEEDED`	Amount or count exceeds configured limit	No
`SCREENING_BLOCKED`	Payment blocked by sanctions screening	No
`ROUTING_FAILED`	No matching route found	Maybe
`PROVIDER_ERROR`	Provider returned a transient error	Yes
`PROVIDER_DECLINED`	Provider declined the transaction	No
`NO_ACTIVE_FLOW`	No published flow for this payment type	No

Security Concepts

OMNYTH supports field-level encryption, payload signing, and HMAC verification — all configurable via security policies in the platform.

Encryption — AES-GCM or AES-CBC encryption for specific fields or full payloads. Keys are managed via keystores or HSM references.
Signing — JWS RS256 signatures on outbound provider requests, verifiable by providers using the published public key.
HMAC — HMAC-SHA256 integrity verification on inbound webhooks and callbacks.

Security policies are attached to service integrations in the platform. Enabling or disabling security does not require application code changes.