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

# Rules & Process Flow

> Operational rules, gateway filtering, and controller/service responsibilities for Collections.

## 1) Rules

### Authentication & Security

* Never expose **API keys/secrets** in logs, traces, or error messages.
* Encrypt sensitive data (API secrets, private keys) **at rest** and **in transit**.
* Scope tokens to products; use the correct token for **Collections** vs **Payouts/Remittance**.
* Store Bearer tokens server-side; rotate and revoke when necessary.

### Data Validation & Integrity

* Validate **all inputs** before processing (type, length, format, enums).
* Enforce **mandatory fields** (reject null/empty).
* Constrain types/lengths to prevent overflows and unexpected errors.
* Ensure request bodies conform to your **JSON Schema** (reject on validation errors).
* Defend against **SQL Injection**, **XSS**, and deserialization attacks.

### Message Queue Processing (RabbitMQ & NATS)

* Use **durable queues** to prevent message loss.
* Configure **DLQs (dead-letter queues)** for failures.
* Make messages **idempotent** (e.g., use `transaction.reference` as the idempotency key).
* Implement **retries with exponential backoff** for transient errors.

### Logging & Monitoring

* Log requests/responses **without** sensitive fields (no secrets/tokens/signatures).
* Use **structured logging** (JSON fields for correlation IDs, reference IDs, user agent).
* Monitor MQ depths, DLQ rates, and processing latencies; alert on anomalies.
* Maintain **audit logs** for critical ops (logins, config changes, key rotations).

***

## 2) Collections Request - Contract (post-auth validation)

After the Bearer token is validated, the following fields are required/validated:

| JSON Path                  | Type   | Description                                     | Required |
| -------------------------- | ------ | ----------------------------------------------- | -------- |
| `transaction.reference`    | string | Client-unique idempotency key                   | YES      |
| `transaction.amount`       | string | Transaction amount                              | YES      |
| `transaction.description`  | string | Description of the collection/remittance        | YES      |
| `transaction.currency`     | string | Currency code (e.g., `KES`)                     | YES      |
| `transaction.timestamp`    | string | Client-initiated timestamp string               | YES      |
| `originator.msisdn`        | string | Originating phone number (MSISDN)               | YES      |
| `originator.country`       | string | Country code (e.g., `KE`)                       | YES      |
| `originator.channel`       | string | Channel/device (e.g., `USSD`, `API`)            | YES      |
| `transaction.service_code` | string | Service to consume (e.g., `RMT_WU`)             | YES      |
| `recipient.reference`      | string | Client-unique reference for recipient context   | YES      |
| `recipient.account`        | string | Customer account identifier (phone/wallet/bank) | YES      |
| `callback_url`             | string | HTTPS webhook for final status                  | YES      |
| `meta.note`                | string | Additional description/notes                    | YES      |
| `meta.agent_id`            | string | Agent identifier                                | YES      |

<Note>
  Follow your configured <code>transaction.service\_code</code> contract for which fields are enforced.
</Note>

**Special Handling**

* Missing/invalid token → **401 Unauthorized**.
* Missing `transaction.service_code` → **403 Forbidden**.
* Duplicate `transaction.reference` → handle gracefully (idempotent response).

**Reference headers**

```http theme={null}
Authorization: Bearer <JWT Token>
Content-Type: application/json
```