# Bulk Payments via SFTP

Use BCB SFTP to submit high-volume payment files in a secure, structured way.

**New to this channel?** Start with [Getting Started: Bulk Payments via SFTP](/guides/bulk-payments-sftp-getting-started) for the end-to-end customer journey (credentials, configuring your SFTP client, and what to do before you upload files).

## 1. Overview

The **Bulk Payments** service allows clients to submit multiple payment instructions in a single **ISO 20022 `pain.001`** file.

BCB provisions dedicated SFTP credentials (a unique username and SSH key) and a client-isolated remote directory for each client.
Clients connect using their preferred SFTP tool or treasury platform and upload files to `/input`.


```mermaid
sequenceDiagram
    participant customer as Customer
    participant bcbSftp as BCB_SFTP
    participant bulkEngine as Bulk_Payments_Engine
    participant cbalT24 as CBAL_T24

    customer->>bcbSftp: Upload pain.001 to /input
    bcbSftp->>bulkEngine: New file detected
    bulkEngine->>bulkEngine: Validate format and duplicate checks
    bulkEngine->>bulkEngine: Create batch record and archive original
    loop Per payment instruction
      bulkEngine->>cbalT24: Submit individual payment
      cbalT24-->>bulkEngine: Status or result
    end
    bulkEngine->>bcbSftp: Write pain.002 output artifact
    bulkEngine->>bcbSftp: Write daily camt.053 reconciliation
    bulkEngine->>bcbSftp: Move final artifacts to /output
```

## 2. Payment Rail Support

The current Bulk Payments scope supports:

- SWIFT payments, using ISO 20022 `pain.001`.
- Local ACH (Automated Clearing House) payment files.


## 3. SFTP Connectivity (UAT)

Use the following connection details:

- **Host:** `stbcbpaymentstest.blob.core.windows.net`
- **Port:** `22`
- **Username:** Provisioned per client (for example: `stbcbpaymentstest.<client-id>`)
- **Authentication:** Client-specific SSH private key


### Example (OpenSSH CLI)


```bash
sftp -i /path/to/private-key <provisioned-username>@stbcbpaymentstest.blob.core.windows.net
```

## 4. Connect Using Your Preferred Tool

You can connect using:

- Any SFTP desktop client
- Command-line SFTP tooling
- Treasury or payment platforms with SFTP file-drop capability
- Managed file transfer (MFT) solutions


Use this connection profile:

- **Protocol:** `SFTP`
- **Host:** `stbcbpaymentstest.blob.core.windows.net`
- **Port:** `22`
- **Username:** `<provisioned-username>`
- **Authentication:** Provisioned SSH private key


### Key format notes

- OpenSSH private keys are commonly used.
- Some tools may require key conversion into a tool-specific format.
- Save the connection profile for repeat batch submissions.


## 5. Directory Structure

Each client receives a dedicated SFTP directory with the following folders:

| Folder | Purpose |
|  --- | --- |
| `/input` | Client drops `pain.001` files here. |
| `/output` | Final batch artifacts are placed here once processing completes (successful or not). `pain.002` and end-of-day `camt.053` outputs are delivered here. |
| `/archive` | Original submitted files are archived after ingestion. |


## 6. Processing Lifecycle

When a `pain.001` file is uploaded to `/input`, the platform:

1. Detects the new file.
2. Validates file format and performs duplicate detection.
3. Creates a batch record.
4. Archives the original file.
5. Processes each payment instruction independently through existing payment controls.
6. Publishes completion artifacts to `/output`.


Important behavior:

- Batch processing is **non-atomic**.
- Individual payments can succeed or fail independently.
- External client flow is **`/input` to `/output`**.
- Output handling is **batch-oriented**; individual transaction completion files are written per batch into a `pain.002` file.
- End-of-day reconciliation file `camt053-YYYY-MM-DD.xml` is delivered to `/output`.


## 7. Status and Reconciliation

### Illustrative batch statuses

- `RECEIVED`
- `VALIDATED`
- `IN_PROGRESS`
- `SUBMITTED`
- `COMPLETED`
- `PARTIALLY_FAILED`
- `FAILED`


### Result delivery channels

- SFTP output files
- API status polling endpoint
- Optional webhook notifications
- End-of-day reconciliation file (`camt053-YYYY-MM-DD.xml`) in `/output`


## 8. Output and Archive Artifacts

These examples define typical output and archive patterns.

| Folder | Example filename | Purpose |
|  --- | --- | --- |
| `/output` | `PAYMENT-BATCH-B-001_pain002.xml` | Batch and transaction-level status summary file in `pain.002` XML format. |
| `/output` | `{Tenant}-{Id}-YYYYMMDD_camt053.xml` | End-of-day account and reporting file. |
| `/archive` | `pain.001.001.03.bulk.case-b-round-numbers.xml` | Original uploaded input file retained for traceability. |


## 9. Status Definitions and Client Actions

| Batch status | What it means | Client action |
|  --- | --- | --- |
| `RECEIVED` | File has been accepted for intake. | Wait for validation. |
| `VALIDATED` | File structure and core checks passed. | Wait for processing. |
| `IN_PROGRESS` | Payments are being processed. | Monitor status and output; no action needed. |
| `SUBMITTED` | Instructions submitted to downstream systems. | Continue monitoring until terminal status. |
| `COMPLETED` | Batch finished with no known failures. | Reconcile totals and archive your local copy. |
| `PARTIALLY_FAILED` | Some instructions succeeded and some failed. | Download summary and reconciliation outputs, correct failed items, and resubmit as needed. |
| `FAILED` | Batch failed validation or processing. | Review error details, correct the file, and resubmit with a new batch or message reference. |


## 10. Sample Files (Happy Path)

The following sample files are based on the same `pain.001.001.03` bulk structure and include different amount distributions.

For each file:

- `NbOfTxs` = `10`
- `CtrlSum` is set to the exact sum of all `InstdAmt` values.


| Test case | CtrlSum (USD) | Download |
|  --- | --- | --- |
| Case A - low values | `50.34` | [pain.001.001.03.bulk.case-a-low-value.xml](/sftp-test-files/pain.001.001.03.bulk.case-a-low-value.xml) |
| Case B - round numbers | `550.00` | [pain.001.001.03.bulk.case-b-round-numbers.xml](/sftp-test-files/pain.001.001.03.bulk.case-b-round-numbers.xml) |
| Case C - mixed values | `605.04` | [pain.001.001.03.bulk.case-c-mixed-values.xml](/sftp-test-files/pain.001.001.03.bulk.case-c-mixed-values.xml) |
| Case D - high values | `51234.51` | [pain.001.001.03.bulk.case-d-high-value.xml](/sftp-test-files/pain.001.001.03.bulk.case-d-high-value.xml) |


## 11. Validation Files (Failure Cases)

These files are intentionally designed to fail specific controls.

| Failure case | Expected behavior | Download |
|  --- | --- | --- |
| Duplicate `MsgId` (first submission) | First submission should process normally. | [pain.001.001.03.bulk.fail-duplicate-msgid-first.xml](/sftp-test-files/pain.001.001.03.bulk.fail-duplicate-msgid-first.xml) |
| Duplicate `MsgId` (repeat submission) | Second submission should be flagged as duplicate. | [pain.001.001.03.bulk.fail-duplicate-msgid-second.xml](/sftp-test-files/pain.001.001.03.bulk.fail-duplicate-msgid-second.xml) |
| Invalid `CtrlSum` | Validation should fail due to amount total mismatch. | [pain.001.001.03.bulk.fail-invalid-ctrlsum.xml](/sftp-test-files/pain.001.001.03.bulk.fail-invalid-ctrlsum.xml) |
| Invalid `NbOfTxs` | Validation should fail due to transaction count mismatch. | [pain.001.001.03.bulk.fail-invalid-nboftxs.xml](/sftp-test-files/pain.001.001.03.bulk.fail-invalid-nboftxs.xml) |
| Invalid execution date format | Validation should fail due to non-ISO date format. | [pain.001.001.03.bulk.fail-invalid-date-format.xml](/sftp-test-files/pain.001.001.03.bulk.fail-invalid-date-format.xml) |


## 12. Security and Controls

- Client-isolated SFTP directories
- Secure file handling and storage
- No cross-client data visibility
- End-to-end auditability of batch lifecycle and payment transitions
- Observability through operational metrics and dashboards


## 13. Support

For onboarding and integration support, contact:

- **Email:** [api@bcb.bm](mailto:api@bcb.bm)