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
| Header | Used 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
- Money: strings with exactly 2 decimals, e.g.
"8500.00". JSON numbers with a fraction are rejected (no float). - Currency:
SARonly (MVP). - IBAN: Saudi IBAN, 24 chars, ISO 13616 mod-97 check. Spaces are stripped.
- Idempotency:
external_refof a batch is unique per tenant. Same ref + same payload ⇒ same batch (200). Same ref + different payload ⇒ 409. - Actors:
created_by,submitted_by,approver_ref,sent_by,actorare the caller's user ids (e.g.user:57). With a portal session these are taken from the session and cannot be supplied.
Error codes
| HTTP | Meaning |
|---|---|
| 400 | Invalid input (message explains the field) |
| 401 | Missing/invalid key or session |
| 402 | Subscription 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) |
| 403 | Maker-checker rule, approver limit, role |
| 404 | Not found or not yours |
| 409 | State conflict (wrong status, file hash mismatch, duplicate approval, idempotency clash) |
| 429 | Rate limit |
| 502 | Bank 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
- The pain.001 file is built at submit; its
file_sha256is returned. Approvers approve that exact hash. sendre-checks the hash and transmits the identical bytes.- The creator and the submitter can never approve. Each approver approves once.
max_amountper approver ≥ batch total.approvals_required(1–3) is set on the tenant. returnvoids all approvals of the round; resubmission starts a new round.- Line status:
pending | accepted | rejectedwithbank_status(ISO code e.g.ACSC,RJCT) andreason_code(e.g.AC04). Accepted set:ACCP ACSP ACSC ACCC ACWC ACWP. Rejected:RJCT CANC. Everything else (incl.ACTC,PDNG,RCVD) stayspending.
4. Endpoints
Public
| Method | Path | Notes |
|---|---|---|
| GET | /v1/health | version, XSD availability |
| GET | /v1/banks | bank profiles; fields not publicly documented are "يُستكمل من مستند البنك عند توقيع اتفاقية H2H" and listed in pending_fields |
Tenants, approvers, connections
| Method | Path | Body |
|---|---|---|
| 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}/poll | pulls pain.002 + camt files from the channel and applies them |
Adapter config (non-secret) and secrets:
| adapter | config | secrets |
|---|---|---|
manual | – | – |
sandbox | – (only with bank_code=sandbox; every response is marked simulated: true) | – |
sftp_generic | host, 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_generic | base_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
| Method | Path | Body |
|---|---|---|
| POST | /v1/tenants/{tid}/batches | see 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}/file | application/xml, header X-File-SHA256 (after submit) |
| GET | /v1/batches/{bid}/audit | audit 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
| Method | Path | Body |
|---|---|---|
| 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/run | proposes matches |
| POST | /v1/tenants/{tid}/entries/{eid}/confirm · /reject | {actor} |
Matching rules (amount alone never matches):
| rule | condition | result |
|---|---|---|
e2e+amount | debit entry EndToEndId = line, same amount | proposed / high |
e2e_amount_diff | same EndToEndId, different amount | exception |
batch_ref+total | bulk entry with PmtInfId/MsgId of a batch, amount = batch total (or accepted total) | proposed / high |
iban+amount | no reference; counterparty IBAN = creditor IBAN, same amount, single candidate | proposed / medium |
return_e2e | credit entry carrying a paid line's EndToEndId | exception |
Audit
| GET | /v1/tenants/{tid}/audit | hash-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.
| Plan | Catalog codes | Channels |
|---|---|---|
| Basic | basic_1 basic_2 basic_3 | manual, sandbox |
| Pro | pro_1 pro_2 pro_3 | + sftp_generic, api_generic |
| Enterprise | custom | all |
Current packages and prices: GET /portal/plans.
6. ISO 20022 coverage
| Message | Direction | Version |
|---|---|---|
| pain.001 Customer Credit Transfer Initiation | out | 001.001.09 (validated against the official XSD when present + structural checks) |
| pain.002 Customer Payment Status Report | in | any version (parsed by element local-name) |
| camt.053 Bank to Customer Statement | in | any version |
| camt.054 Debit/Credit Notification | in | any 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.