Balad ↔ Bank NXT — Remittance Integration

End-to-end flow

1Overview

Balad and Bank NXT exchange remittance data through flat CSV files over SFTP. The integration is bidirectional.

• The inbound transaction file carries PII and account data and is PGP-encrypted.
• The outbound status file contains no sensitive data and is transferred plain (unencrypted).

2Transport & Security

2.1 SFTP

• Transport is SFTP only.
• Authentication: SSH key pair (public keys exchanged out-of-band during onboarding).
• Atomic upload: write to a temporary name, then rename to the final name once the upload completes, so the consumer never reads a partial file.

/inbound/    # files received from the counterparty
/outbound/   # files placed for the counterparty to collect
/archive/    # processed files (optional, per retention policy)

2.2 PGP — inbound transaction file only

• Encrypted with OpenPGP (RFC 4880) using the recipient's public key, signed with the sender's private key.
• Cipher: AES-256; hash: SHA-256 or stronger.
• Encrypted payload filename: cleartext name with .pgp appended.
• The status file (Bank NXT → Balad) is not encrypted.

3File Naming Convention

3.1 Transaction file — Balad → Bank NXT (encrypted)

{BaladReferenceNo}_{YYYYMMDD}_{HHMMSS}.csv        (cleartext)
{BaladReferenceNo}_{YYYYMMDD}_{HHMMSS}.csv.pgp    (on SFTP)

Example: BLDREF00001_20260604_095231.csv

3.2 Status Update file — Bank NXT → Balad (plain)

{BaladReferenceNo}_Status_Update.csv

Example: BLDREF00001_Status_Update.csv

4Transaction File (Balad → Bank NXT)

4.1 File-level rules

4.2 Column specification

Columns appear in the exact order below.

4.3 Header row (exact)

BaladReference,TransactionCreatedAt,SenderFullName,SenderFullNameAr,SenderNationality,SenderDOB,ReceiverName,ReceiverNameAr,ReceiverContactNumber,TransactionType,BusinessModel,PayoutAmount,PayoutCurrency,DestinationBank,AccountNumber,WalletMobileNumber,PurposeOfTransfer

5Lookup / Reference Data

Agreed enumerations for the coded columns. Kept in sync between both parties; changes are versioned and communicated before use.

5.1 Purpose of Transfer (PurposeOfTransfer)

Codes are 3-digit zero-padded strings.

5.2 Transaction Types (TransactionType)

5.3 Banks (DestinationBank)

5.4 Business Model (BusinessModel)

6Status Update File (Bank NXT → Balad)

Plain (unencrypted) CSV. Multiple rows per BaladReference are expected — one per lifecycle event.

6.1 File-level rules

6.2 Column specification

Header row (exact):

BaladReference,Status,StatusTimestamp,AdditionalInfo

6.3 Status values

The set of Status values (and rejection reasons) is owned and shared by Bank NXT. They are emitted at each step of Bank NXT's processing workflow — see §7. Bank NXT Processing Workflow.

7Bank NXT Processing Workflow (BPMN)

How Bank NXT processes each batch and the statuses it writes to the status file at every step. Source: Bank NXT – EDE – Balad project – BPMN – workflow – V0.13. Payment instructions are processed in parallel per record.

flowchart TD
    Start([Robot listens for new file]) --> A{New master file added?}
    A -- No --> Start
    A -- Yes --> B[Create batch processing log file]
    B --> C[["All records status = Received"]]
    C --> P[/Process payment instructions in parallel/]

    P --> BM{Business Model = C2C?}
    BM -- No --> RJ1[["Rejected — Business model is not C2C"]]
    BM -- Yes --> BAL[Check funding account balance]
    BAL --> SB{Sufficient balance?}
    SB -- No --> RJ2[["Rejected — Insufficient balance"]]
    SB -- Yes --> LOCK[Lock funding amount + commission + fees]

    LOCK --> COMP[["Check Compliance SAS — status = Under Compliance Review"]]
    COMP --> WAIT1[Waiting for compliance response]
    WAIT1 --> HIT{Hit?}
    HIT -- Yes --> UNL1[Unlock funding amount] --> RJ3[["Rejected — Compliance rejected"]]
    HIT -- No --> APP[["status = Compliance approved"]]

    APP --> RT{Routing type?}

    RT -- On-Us internal transfer --> VAL["Validate bank customer - CIF and sub-account in T24"]
    VAL --> V{Valid?}
    V -- No --> RJ4[["Rejected — Invalid CIF / receiving account"]]
    V -- Yes --> CORE[["status = Sent to core"]]
    CORE --> POST1["Post accounting entries and transfer to receiver"]
    POST1 --> PD{Posted?}
    PD -- Yes --> TR1[["status = Transferred"]]
    PD -- No --> UNL2[Unlock funding amount] --> RJ5[["Rejected — Internal transfer not posted"]]

    RT -- Third-party bank --> ACH1[["status = Sent to ACH"]]
    ACH1 --> POST2["Post accounting entries and send ACH to bank"]
    POST2 --> AW[["status = Awaits ACH response"]]
    AW --> WAIT2[Waiting for ACH response]
    WAIT2 --> TRD{Transferred?}
    TRD -- Yes --> TR2[["status = Transferred"]]
    TRD -- No --> REV[Reverse accounting entries] --> RJ6[["Rejected — ACH failed"]]
    

7.1 T24 customer validation (sub-process)

flowchart TD
    S([Start]) --> VC[Validate CIF]
    VC --> Q1{Valid CIF number?}
    Q1 -- No --> R1[["Rejected — Invalid CIF"]]
    Q1 -- Yes --> VS["Validate sub-account and match transaction currency"]
    VS --> Q2{Valid sub-account?}
    Q2 -- No --> R2[["Rejected — Invalid receiving account"]]
    Q2 -- Yes --> OK([Valid → continue])
    

7.2 Statuses & rejection reasons

Rejection reasons: Business model is not C2C · Insufficient balance · Compliance rejected · Invalid CIF · Invalid receiving account · Internal transfer not posted · ACH failed.

8Processing & Validation Rules

1. Filename — reject files not matching the naming convention (§3).
2. PGP — reject inbound files that fail decryption or signature verification.
3. Header — column names and order must match exactly (§4.3 / §6.2).
4. Encoding — files must be valid UTF-8; reject on decode errors (protects Arabic fields).
5. Mandatory fields — reject rows missing any required field.
6. Lookup validation — coded columns must exist in the reference tables (§5).
7. Conditional fields — enforce the per-TransactionType requirements.
8. Amount — PayoutAmount > 0, max 2 decimals; valid ISO 4217 currency.
9. Datetime — all datetimes in UTC, dd-MMM-yyyy hh:mm:ss tt (e.g. 18-JUN-2026 11:11:39 AM).
10. Reference uniqueness — BaladReference unique within a batch.
11. Status matching — every status BaladReference must correspond to a previously sent transaction.

9Open Items / To Confirm