> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentco.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guide

This guide explains how to implement the Billing File (SFTP File Ingestion) pattern with Moment.\
It enables merchants to present bills across Moment's online and in-person network using a low-code, file-based workflow.

***

## Pattern Overview

A low-code, standardized pattern that works with any billing system using one pre-defined schema.

Merchants:

* Populate billing data
* Deliver files via SFTP

Moment handles validation, ingestion, and bill presentation.

***

## When to Use This Pattern

Use this pattern if:

* You want minimal engineering effort
* You prefer SFTP file delivery over APIs
* You want the fastest path to bill presentment

You may migrate to the Billing API later for real-time needs.

***

## Integration Responsibilities

### What the Merchant Provides

#### Billing File Format

Each billing file includes:

1. **Customer information** (Items 1–6)
2. **Amount payable** (Items 7–8)
3. **Optional metadata** — biller-specific fields that support internal system requirements

***

#### File Schema

| Item | Item Name       | Field Name                 | Type    | Example                                     | Required      |
| ---- | --------------- | -------------------------- | ------- | ------------------------------------------- | ------------- |
| 1    | First Name      | first\_name                | String  | John                                        | True          |
| 2    | Last Name       | last\_name                 | String  | Doe                                         | True          |
| 3    | Passport Number | passport\_number           | String  | P12345678                                   | Either 3 or 4 |
| 4    | SA ID Number    | sa\_identification\_number | Decimal | 8501015800085                               | Either 3 or 4 |
| 5    | Mobile          | mobile\_phone\_number      | Decimal | 0821234567                                  | False         |
| 6    | Email           | email                      | String  | [john@example.com](mailto:john@example.com) | False         |
| 7    | Due Date        | due\_date                  | Date    | 2025-02-20                                  | False         |
| 8    | Amount Due      | amount\_due                | Decimal | 240.00                                      | True          |

**Identifier rules:**

* Merchant may choose any unique identifier (account number, policy number, subscriber ID, etc.)
* Prefer numeric, under 16 digits
* Moment can generate identifiers on request

***

#### File Delivery Requirements

| File Type              | Cadence  | Delivery Time (UTC) | Type | Naming Convention                                          |
| ---------------------- | -------- | ------------------- | ---- | ---------------------------------------------------------- |
| Full customer file     | One-time | N/A                 | CSV  | `[country]_[merchant]_moment_all-customers_YYYY-MM-DD.csv` |
| Daily incremental file | Daily    | 6am SAST            | CSV  | `[country]_[merchant]_dailyfile_YYYY-MM-DD.csv`            |

#### Missed File Handling

If a daily file is missed, include all applicable updates in the next file.

| Date  | Daily File    | Notes                             |
| ----- | ------------- | --------------------------------- |
| 1 Feb | Not delivered |                                   |
| 2 Feb | Delivered     | Includes updates from 1 and 2 Feb |

***

### What Moment Does

* Validates file structure and content
* Ingests bills
* Makes bills discoverable via all payment channels
* Generates settlement and reconciliation files

***

### What Customers See

1. Enter identifier
2. View bill details
3. Confirm and pay

***

# End-to-End Flow

**1. Billing File Creation**\
Merchant prepares a billing CSV file.

**2. Secure File Delivery (SFTP)**\
Daily cadence may introduce up to 24 hours of data staleness.

**3. Validation and Intake**\
Moment validates and ingests the file.

**4. Enquiry at Payment Channel**\
Customer enters identifier → Channel queries Moment → Bill returned.

**5. Payment**\
Customer pays → Channel notifies Moment.

**6. Reconciliation**\
Moment provides webhook notifications or SFTP settlement files.

***

## Sequence Flow

```mermaid theme={"system"}
sequenceDiagram
    participant Biller as Biller System
    participant Moment as Moment Platform
    participant Channel as Payment Channel
    participant Customer as Customer

    %% Billing data (file-based)
    Biller->>Moment: Upload billing file (SFTP)
    Moment-->>Biller: Acknowledge file (optional)

    %% Enquiry
    Customer->>Channel: Enter identifier
    Channel->>Moment: Bill enquiry (identifier)
    Moment-->>Channel: Bill details (amount, metadata)
    Channel-->>Customer: Display bill details

    %% Payment
    Customer->>Channel: Confirm payment
    Channel->>Moment: Payment request
    Moment-->>Channel: Payment result
    Channel-->>Customer: Show receipt / confirmation

    %% Reconciliation
    Moment->>Biller: Reconciliation & settlement files (SFTP)
    Biller-->>Biller: Update internal ledger / post payments


```

***

# Best Practices and Notes

## Identifier Consistency

The identifier used in your billing file must be the same identifier entered by customers during enquiry.

The merchant defines this identifier (e.g., account number, subscriber ID, policy number).

***

## Data Freshness

Choose a file delivery cadence that aligns with your business needs:

| Cadence | Trade-Off                                                                   |
| ------- | --------------------------------------------------------------------------- |
| Hourly  | Near real-time updates; higher operational overhead                         |
| Daily   | Most common; straightforward to maintain; amounts may be up to 24 hours old |
| Weekly  | Suitable for non-urgent billing cycles                                      |

***

## Fulfillment and Financial Reporting

* SFTP reconciliation and settlement files are the source of truth
* Optional webhooks allow near-real-time notifications
* Reconciliation files should be used for internal posting and ledger updates

***

## Security

* SFTP keys and access credentials are provisioned securely during onboarding
* Access is permissioned per merchant and monitored