OCTA Bank Gateway — API Specification (v0.1.0)

Base URL (production, configurable): https://bank.medcoreapp.tech All bodies are JSON (UTF-8) unless stated. All responses:

{"success": true,  "data": ...}
{"success": false, "error": "human-readable message (Arabic)", ...}

1. Authentication

HeaderUsed by
X-API-Key: obk_…Server-to-server (MedCore, any subscribed system). One key per app.
Authorization: Bearer <session>Customer portal session (a named member).

A tenant (facility) belongs to exactly one app. Any id from another app returns 404 (not 403). Rate limit: RATE_LIMIT_PER_MINUTE per app (default 600) → 429.

2. Conventions

Error codes

HTTPMeaning
400Invalid input (message explains the field)
401Missing/invalid key or session
402Subscription inactive or expired, paid account quota reached, or channel not in plan (Basic = manual only; sftp_generic/api_generic need Pro). Body may include upgrade_url (sandbox is exempt)
403Maker-checker rule, approver limit, role
404Not found or not yours
409State conflict (wrong status, file hash mismatch, duplicate approval, idempotency clash)
429Rate limit
502Bank channel error (batch returns to approved, safe to retry)

3. Batch lifecycle

draft ──submit──► submitted ──approve × N──► approved ──send──► sent ──pain.002──► accepted
  ▲                   │                                           │                partially_accepted
  └──────return───────┘                                           └──────────────► rejected
draft | submitted ──cancel──► cancelled

4. Endpoints

Public

MethodPathNotes
GET/v1/healthversion, XSD availability
GET/v1/banksbank profiles; fields not publicly documented are "يُستكمل من مستند البنك عند توقيع اتفاقية H2H" and listed in pending_fields

Tenants, approvers, connections

MethodPathBody
POST/v1/tenants{external_ref, name, cr_number?, approvals_required? (1-3)} upsert
GET/v1/tenants · /v1/tenants/{tid}
POST/v1/tenants/{tid}/approvers{ref, name, max_amount:"500000.00", active?: true, member_id?} upsert
GET/v1/tenants/{tid}/approvers
POST/v1/tenants/{tid}/connections{bank_code: alrajhi|snb|sandbox, adapter: manual|sftp_generic|api_generic|sandbox, debtor_name, debtor_iban, debtor_bic?, initiating_party_id?, label?, config:{…}, secrets:{…}} → includes readiness[]
GET/v1/tenants/{tid}/connections · /v1/connections/{cid}secrets are never returned; only secrets_configured
PUT/v1/connections/{cid}/secrets{secrets:{…}} replaces all secrets
POST/v1/connections/{cid}/pollpulls pain.002 + camt files from the channel and applies them

Adapter config (non-secret) and secrets:

adapterconfigsecrets
manual––
sandbox– (only with bank_code=sandbox; every response is marked simulated: true)–
sftp_generichost, port?, username, host_key ("SHA256:…" or "ssh-ed25519 AAAA…"), upload_dir, status_dir, statements_dir, upload_temp_suffix?, file_security?private_key (PEM) and/or password, passphrase?
api_genericbase_url (https), submit_path, status_path, statements_path, auth (mtls|bearer|mtls+bearer), submit_content_type?, reference_field?, timeout_seconds?client_cert_pem, client_key_pem, bearer_token

Optional config.pain001_options (only values confirmed in writing by the bank): charge_bearer (DEBT|CRED|SHAR|SLEV), batch_booking (bool), latin_only_names (bool), category_purpose (bool, default true).

Batches

MethodPathBody
POST/v1/tenants/{tid}/batchessee below → 201 (created) / 200 (idempotent replay)
GET/v1/tenants/{tid}/batches?status=summaries
GET/v1/batches/{bid}full batch with lines and approvals
GET/v1/batches/{bid}/fileapplication/xml, header X-File-SHA256 (after submit)
GET/v1/batches/{bid}/auditaudit rows of the batch
POST/v1/batches/{bid}/submit{submitted_by}
POST/v1/batches/{bid}/approve{approver_ref, file_sha256, note?}
POST/v1/batches/{bid}/return{approver_ref, note} (note required)
POST/v1/batches/{bid}/cancel{actor, reason?} (draft/submitted only)
POST/v1/batches/{bid}/send{sent_by} → channel_result

Create batch body:

{
  "external_ref": "payroll-2026-11",
  "connection_id": "…",
  "kind": "salary",                     // salary → CtgyPurp SALA · supplier → SUPP
  "requested_date": "2026-11-27",       // today..+90 days (Riyadh), default today
  "description": "Payroll Nov 2026",
  "created_by": "user:12",
  "lines": [
    {"external_ref": "emp-301", "creditor_name": "…", "creditor_iban": "SA…",
     "amount": "8500.00", "creditor_bic": null, "purpose_code": null, "remittance": "Salary Nov"}
  ]
}

Max 5,000 lines. The gateway assigns msg_id, pmt_inf_id, and per line end_to_end_id / instr_id (≤35 chars, SWIFT charset). Keep end_to_end_id — it is the reconciliation key.

Bank files, statements, reconciliation

MethodPathBody
POST/v1/tenants/{tid}/inbound{name, content_b64, connection_id?} or raw XML body. Auto-detects pain.002 / camt.053 / camt.054. Duplicate files (sha256) are ignored.
GET/v1/tenants/{tid}/statements · /v1/tenants/{tid}/statements/{sid}
GET/v1/tenants/{tid}/entries?match_status=unmatched|proposed|exception|confirmed|rejected
POST/v1/tenants/{tid}/reconciliation/runproposes matches
POST/v1/tenants/{tid}/entries/{eid}/confirm · /reject{actor}

Matching rules (amount alone never matches):

ruleconditionresult
e2e+amountdebit entry EndToEndId = line, same amountproposed / high
e2e_amount_diffsame EndToEndId, different amountexception
batch_ref+totalbulk entry with PmtInfId/MsgId of a batch, amount = batch total (or accepted total)proposed / high
iban+amountno reference; counterparty IBAN = creditor IBAN, same amount, single candidateproposed / medium
return_e2ecredit entry carrying a paid line's EndToEndIdexception

Audit

GET/v1/tenants/{tid}/audithash-chained rows (prev_hash, hash)
GET/v1/tenants/{tid}/audit/verify{ok, entries, head} or {ok:false, broken_at_seq}

hash = sha256(prev_hash + canonical_json(scope, seq, at, app_id, tenant_id, batch_id, actor, action, detail)).

Webhooks (gateway → your app)

POST /v1/webhook {url} (https only) returns a secret once. Events: batch.status_changed {event, batch_id, external_ref, tenant_id, tenant_external_ref, status, total, currency, at}. Headers: X-Octa-Event, X-Octa-Delivery, X-Octa-Timestamp (ms), X-Octa-Signature = hex(HMAC-SHA256(secret, "{timestamp}.{raw_body}")). Retries: 1m, 5m, 15m, 60m, 6h, then failed. Verify with verify_webhook() in octa_bank_client.py. Treat webhooks as hints: always re-read GET /v1/batches/{id}.

5. Plans (for subscribed businesses)

Internal OCTA apps (keys from /admin/apps) have no limits. Subscribed businesses buy prepaid packages of 3, 6 or 12 months on octasolutions.net (no monthly subscription); /provision activates them. The unit is a connected (non-sandbox) bank account.

PlanCatalog codesChannels
Basicbasic_1 basic_2 basic_3manual, sandbox
Propro_1 pro_2 pro_3+ sftp_generic, api_generic
Enterprisecustomall

Current packages and prices: GET /portal/plans.

6. ISO 20022 coverage

MessageDirectionVersion
pain.001 Customer Credit Transfer Initiationout001.001.09 (validated against the official XSD when present + structural checks)
pain.002 Customer Payment Status Reportinany version (parsed by element local-name)
camt.053 Bank to Customer Statementinany version
camt.054 Debit/Credit Notificationinany version

Bank-specific usage rules (naming, encryption, charset, ChrgBr, BtchBookg, InitgPty id scheme, versions accepted) are not invented. They stay PENDING in the bank profile until the bank's H2H document is signed.