Renegan API documentation

1. Discovery & alignment — Confirm use cases (rules, thresholds, alert handling) with your Renegan contact.
2. Credentials & environment — Receive an API key and the base URL for your sandbox or production region.
3. Integrate injection — Send transactions to the inject endpoint from your payment or core banking flow.
4. Validate & tune — Compare outcomes in the Renegan console, then adjust rules and payloads with your implementation team.

2. Authentication

• Transaction injection — header x-client-api-key and Content-Type: application/json. Requires active billing and transaction monitoring on the org tied to the key.
• Fraud rules & AML — HTTP header Authorization: Bearer <access_token> (same JWT flow as the Renegan web app). Routes use org RBAC, billing access, and (for rules) the fraud detection feature flag.
• Call injection from your backend when you can. Browser calls with an API key need CORS to allow x-client-api-key.

3. Inject transaction

Submit a single transaction for scoring and monitoring.

curl -X POST "https://{API_HOST}/api/transaction/inject" \
  -H "Content-Type: application/json" \
  -H "x-client-api-key: YOUR_API_KEY" \
  -d @payload.json

4. Request payload

JSON body fields map to BaseTransactionReqDto in the API. currency must be one of the supported ISO 4217 enum values. direction is inbound or outbound from the customer account’s perspective. Boolean-like flags use the strings "true" or "false" where noted in the DTO. Optional transactionId is your reference and is stored on the transaction; Renegan always assigns its own primary id returned as data.id (tx_ plus a ULID).

{
  "transactionId": "0fd471d7-7f62-4d8a-a7aa-648ebb14d9b5",
  "timestamp": "2025-03-25T12:01:00.000Z",
  "amount": 50000.67,
  "currency": "NGN",
  "channel": "bank_transfer",
  "narration": "Payment for goods",
  "direction": "outbound",
  "customerEmail": "user@example.com",
  "customerBankAccount": "1243567890",
  "customerBankCode": "011",
  "customerAccountName": "Jane Customer",
  "customerAccountType": "savings",
  "customerIpAddress": "102.89.25.11",
  "customerGeolocation": "Lagos, Nigeria",
  "isCustomerAccountNew": "false",
  "customerHistoricalAverageTxn": 20000,
  "customerVelocityCount": 2,
  "customerLastTxnDate": "2025-03-20T09:15:00.000Z",
  "customerLastTxnAmount": 15000,
  "customerRiskCategory": "medium",
  "customerLastTxnDirection": "inbound",
  "customerCreatedAt": "2024-06-01T00:00:00.000Z",
  "customerBalanceBeforeTxn": 120000,
  "customerDateOfBirth": "1990-01-01",
  "customerName": "Jane Customer",
  "customerPEP": "false",
  "customerLoginCountry": "Nigeria",
  "customerDeviceId": "device_abc_123",
  "receiverAccountNumber": "9988776655",
  "recieverBankCode": "070",
  "recieverAccountName": "Merchant Ltd",
  "beneficiary_sort_code": 123456,
  "firstTimeReciever": "true",
  "receiverCountry": "Nigeria",
  "receiverBankCountry": "Nigeria"
}

Field names reflect the live API contract, including recieverBankCode spelling.

5. Response

Successful injection returns HTTP 201 with a GenericStatus envelope (statusCode, description, data). The controller still documents BaseTransactionResDto in Swagger for this route, but the running service returns the slimmer object below from injectTransaction.

{
  "statusCode": 201,
  "description": "Transaction injected",
  "data": {
    "id": "tx_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "status": "approved",
    "triggeredRules": [
      {
        "id": "01BX5ZZKBKACTAV9WEVGEMMVRR",
        "name": "High velocity outbound",
        "outcomes": ["fraud"]
      }
    ]
  }
}

data.status is one of approved, declined, pending, or review. triggeredRules lists rules that fired, each with rule id, name, and outcomes (array of configured outcome strings such as fraud or review; may be empty).

6. Field reference

7. Fraud rules API

Real-time fraud scoring runs when you call transaction injection; there is no separate "score this payload" API key endpoint. To list and toggle which rules apply to your organization, use the rules API with a user access token.

• Requires a signed-in user token, org permissions, active billing, and the fraud detection product feature enabled for those routes.
• Base path (with global prefix): /api/rules.

List rules

GET /api/rules — optional query: page (default 1), take (1–50, default 20), order (ASC | DESC), searchTerm, category, outcomes (fraud | review), isActive "true" or "false".

Response: GenericStatus with HTTP 200, description: "Rules retrieved", and data containing the rules payload from the service (paginated / filtered).

Activate or deactivate a rule

PATCH /api/rules/activate/:ruleId
PATCH /api/rules/deactivate/:ruleId

Responses: GenericStatus with "Rule activated" or "Rule deactivated".

curl -s "{API_HOST}/api/rules?page=1&take=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

8. AML API

AML checks run in the transaction pipeline after injection; the standalone POST screening routes on the controller are currently disabled in code. These authenticated routes let you read stored results, record decisions, and check usage.

• Auth: Authorization: Bearer <access_token> plus org RBAC and billing checks. No extra per-route billing feature flag is attached in code beyond those guards.
• Base path: /api/aml/...

Get screening result

GET /api/aml/results/transaction/:transactionId — by Renegan transaction id (tx_… from injection).
GET /api/aml/results/:resultId
GET /api/aml/results/alert/:alertId

Successful reads return the mapped AML object directly (not wrapped in GenericStatus). Shape follows mapAMLResponse in the service:

{
  "id": "aml_result_ulid",
  "overallRiskScore": 65,
  "overallRiskLevel": "MEDIUM",
  "status": "COMPLETED",
  "providerResults": [
    {
      "name": "…",
      "dateOfBirth": null,
      "country": "…",
      "riskLevel": "…",
      "sourceType": "…",
      "nationality": [],
      "addresses": [],
      "aliasNames": []
    }
  ],
  "decision": null,
  "decisionReason": null,
  "recommendations": []
}

List results for an organization

GET /api/aml/results/organization/:organizationId — query page, limit, optional status, riskLevel. Response body: PageDto — data (array of mapped results) and total.

Decisions

POST /api/aml/results/:resultId/matches/decide

{
  "decisions": [
    {
      "matchId": "match_id_from_combined_matches",
      "decision": "FALSE_POSITIVE",
      "reason": "Optional reviewer note"
    }
  ]
}

decision per match: FALSE_POSITIVE, TRUE_POSITIVE, or WHITELISTED. Response: updated mapped AML object (same shape as GET).

POST /api/aml/results/:resultId/decision

{
  "decision": "FALSE_POSITIVE",
  "reason": "Optional",
  "reviewedBy": "optional_user_id"
}

Usage and health

GET /api/aml/usage/:organizationId → GenericStatus with AML screen usage counters.
GET /api/aml/health → { "status": "healthy", "timestamp": "<ISO>" }.