API reference

Fraud Reporting

Report fraud cases involving Congolese identities — identity usurpation, forged documents, SIM swaps, account takeovers, money laundering and more — into RDCPASS’s national fraud case queue, one at a time or in bulk.

Create

POST /v1/fraud/reports

Batch

POST /v1/fraud/reports/batches

Retrieve

GET /v1/fraud/reports/{id}

Webhooks

fraud_report.created · fraud_report.status_changed

Overview

When your teams detect fraud involving a person who holds — or claims to hold — a Congolese identity, file it with RDCPASS. Each report opens a case with its own case_number, is reviewed by RDCPASS’s fraud investigation unit, and is correlated with reports from every other bank, operator and platform connected to the network. A SIM swap reported by a telecom operator in Lubumbashi can therefore protect the same citizen’s bank account in Kinshasa the same afternoon.

Confirmed cases feed the fraud signals returned by other RDCPASS services and, where the facts call for it, are escalated to the competent authorities. You follow each case through its lifecycle with webhooks or by retrieving it.

Like every RDCPASS endpoint, this call requires the full authentication stack described in Authentication and supports the common Idempotency-Key and Prefer: respond-async headers.

Request modes

Fraud Reporting supports all four request modes. Use batch mode to import your historical case files in one pass. See Single, batch & async for the full model.

Fraud types

Every report carries exactly one type. Choose the most specific type that describes the facts; use other only when none applies.

Request body

Send the following fields as JSON. As with every RDCPASS request, this is the plaintext shape before AES-256-GCM encryption — see Authentication.

Channels

Evidence files accompany the case for its whole lifetime and are only accessible to RDCPASS investigators. Accepted formats are JPEG, PNG and PDF for image and document, CSV and PDF for transaction_log, and MP3 or WAV for audio. A signed URL you provide must stay valid for at least 15 minutes after the call.

Example request

A telecom operator reports a SIM swap followed by unauthorised mobile money transfers:

{
  "type": "sim_swap",
  "subject": {
    "identifier": {
      "type": "rdcpass_id",
      "value": "COD-2103-0214-4937"
    },
    "full_name": "Kabeya Mwamba Tshisekedi",
    "phone_number": "+243812345678"
  },
  "description": "SIM card replaced at an unauthorised agent in Lubumbashi, followed within 40 minutes by three mobile money transfers the customer did not initiate.",
  "occurred_at": "2026-09-24T09:12:00Z",
  "location": {
    "province": "Haut-Katanga",
    "city": "Lubumbashi"
  },
  "amount": {
    "value": 2450000,
    "currency": "CDF"
  },
  "channel": "ussd",
  "evidence": [
    {
      "type": "transaction_log",
      "file": {
        "url": "https://files.example-bank.cd/cases/88213/transfers.csv"
      },
      "description": "Wallet transaction export for 24 September 2026"
    }
  ],
  "reporter_reference": "INC-2026-88213"
}

The same call as a full request in your language. Header values are illustrative placeholders — see Authentication to compute them.

# Body shown in plaintext — encrypt it per /docs/authentication before sending.
curl https://api.rdcpass.cd/v1/fraud/reports \
  -X POST \
  -H "X-RDCPASS-Key-Id: key_live_8f2a1c0e9b" \
  -H "X-RDCPASS-Timestamp: 1790418900" \
  -H "X-RDCPASS-Nonce: 3c7e1a9d-2b4f-4d6a-8e15-9f0b7c2d4a61" \
  -H "X-RDCPASS-IV: q2Vh8Zk1pX0rT7mB" \
  -H "X-RDCPASS-Signature: b61d4e...9a07" \
  -H "Idempotency-Key: 5f0c2a8e-7d41-4b39-a6e2-1c9d8b3f7a50" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sim_swap",
    "subject": {
      "identifier": {
        "type": "rdcpass_id",
        "value": "COD-2103-0214-4937"
      },
      "full_name": "Kabeya Mwamba Tshisekedi",
      "phone_number": "+243812345678"
    },
    "description": "SIM card replaced at an unauthorised agent in Lubumbashi, followed within 40 minutes by three mobile money transfers the customer did not initiate.",
    "occurred_at": "2026-09-24T09:12:00Z",
    "location": {
      "province": "Haut-Katanga",
      "city": "Lubumbashi"
    },
    "amount": {
      "value": 2450000,
      "currency": "CDF"
    },
    "channel": "ussd",
    "evidence": [
      {
        "type": "transaction_log",
        "file": {
          "url": "https://files.example-bank.cd/cases/88213/transfers.csv"
        },
        "description": "Wallet transaction export for 24 September 2026"
      }
    ],
    "reporter_reference": "INC-2026-88213"
  }'

{
  "id": "frd_5c8e1a7d42",
  "object": "fraud_report",
  "livemode": true,
  "case_number": "RDC-FRD-2026-004812",
  "status": "received",
  "type": "sim_swap",
  "reporter_reference": "INC-2026-88213",
  "created_at": "2026-09-26T10:15:02Z"
}

Response

A successful synchronous call returns 200 OK with the new fraud_report.

Case lifecycle

Every case moves from received to under_review, then to one of three terminal statuses. Each change emits fraud_report.status_changed.

Retrieve a report

Fetch the current state of a case at any time with GET /v1/fraud/reports/{id}:

curl https://api.rdcpass.cd/v1/fraud/reports/frd_5c8e1a7d42 \
  -H "X-RDCPASS-Key-Id: key_live_8f2a1c0e9b" \
  -H "X-RDCPASS-Timestamp: 1790418900" \
  -H "X-RDCPASS-Nonce: 3c7e1a9d-2b4f-4d6a-8e15-9f0b7c2d4a61" \
  -H "X-RDCPASS-Signature: b61d4e...9a07"

{
  "id": "frd_5c8e1a7d42",
  "object": "fraud_report",
  "livemode": true,
  "case_number": "RDC-FRD-2026-004812",
  "status": "under_review",
  "type": "sim_swap",
  "reporter_reference": "INC-2026-88213",
  "created_at": "2026-09-26T10:15:02Z"
}

Webhooks

Two events cover the life of a case. Both use the standard envelope and signature described in webhooks.

{
  "id": "evt_2d6f8a1c3e",
  "object": "event",
  "type": "fraud_report.created",
  "livemode": true,
  "created_at": "2026-09-26T10:15:02Z",
  "data": {
    "object": {
      "id": "frd_5c8e1a7d42",
      "object": "fraud_report",
      "case_number": "RDC-FRD-2026-004812",
      "status": "received",
      "type": "sim_swap",
      "reporter_reference": "INC-2026-88213"
    }
  }
}

{
  "id": "evt_8b3e0f7a91",
  "object": "event",
  "type": "fraud_report.status_changed",
  "livemode": true,
  "created_at": "2026-09-29T14:32:00Z",
  "data": {
    "object": {
      "id": "frd_5c8e1a7d42",
      "object": "fraud_report",
      "case_number": "RDC-FRD-2026-004812",
      "type": "sim_swap",
      "status": "confirmed",
      "reporter_reference": "INC-2026-88213"
    },
    "previous_attributes": { "status": "under_review" }
  }
}

Batch: bulk historical case import

When you connect to RDCPASS, import the fraud cases you have already investigated so they strengthen the network from day one. Send up to 10,000 cases per asynchronous batch; each item takes the same fields as a single report, plus a required reference of your own that is echoed back in the results.

# Historical case import — body shown in plaintext; encrypt it per /docs/authentication
curl https://api.rdcpass.cd/v1/fraud/reports/batches \
  -X POST \
  -H "X-RDCPASS-Key-Id: key_live_8f2a1c0e9b" \
  -H "X-RDCPASS-Timestamp: 1790418900" \
  -H "X-RDCPASS-Nonce: 3c7e1a9d-2b4f-4d6a-8e15-9f0b7c2d4a61" \
  -H "X-RDCPASS-IV: q2Vh8Zk1pX0rT7mB" \
  -H "X-RDCPASS-Signature: b61d4e...9a07" \
  -H "Idempotency-Key: 5f0c2a8e-7d41-4b39-a6e2-1c9d8b3f7a50" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d @historical-cases.json

{
  "items": [
    {
      "reference": "case-2025-00114",
      "type": "document_forgery",
      "subject": { "full_name": "Mbuyi Ilunga Nsimba", "date_of_birth": "1991-11-03" },
      "description": "Forged voter card presented to open a savings account at the Gombe branch.",
      "occurred_at": "2025-06-18T11:40:00Z",
      "location": { "province": "Kinshasa", "city": "Kinshasa" },
      "channel": "branch"
    },
    {
      "reference": "case-2025-00167",
      "type": "payment_fraud",
      "subject": { "identifier": { "type": "rdcpass_id", "value": "COD-1907-5521-0386" } },
      "description": "Card-not-present purchases disputed by the cardholder after a phishing SMS.",
      "occurred_at": "2025-08-02T19:05:00Z",
      "location": { "province": "Nord-Kivu", "city": "Goma" },
      "amount": { "value": 1480, "currency": "USD" },
      "channel": "online"
    }
  ]
}

{
  "id": "bat_7c2e91f04a",
  "object": "batch",
  "service": "fraud_reporting",
  "status": "pending",
  "total_items": 3840,
  "processed_items": 0,
  "succeeded_items": 0,
  "failed_items": 0,
  "created_at": "2026-09-26T10:15:00Z",
  "completed_at": null,
  "results_url": "/v1/batches/bat_7c2e91f04a/results"
}

When the batch finishes you receive batch.completed (or batch.completed_with_errors). Page through the per-item results with GET /v1/batches/{batch_id}/results:

{
  "object": "list",
  "data": [
    {
      "reference": "case-2025-00114",
      "status": "succeeded",
      "result": {
        "id": "frd_91a3e0c5b7",
        "object": "fraud_report",
        "livemode": true,
        "case_number": "RDC-FRD-2026-004813",
        "status": "received",
        "type": "document_forgery",
        "reporter_reference": null,
        "created_at": "2026-09-26T10:16:41Z"
      }
    },
    {
      "reference": "case-2025-00167",
      "status": "failed",
      "error": {
        "code": "invalid_identifier",
        "message": "identifier.value is not a valid rdcpass_id."
      }
    }
  ],
  "next_cursor": "cur_b3f10a92"
}

Batches of 50 items or fewer can be sent without Prefer: respond-async; the call then returns 200 OK with every result. Larger synchronous batches are rejected with 413 batch_too_large.

Asynchronous single report

Reports with large evidence files are best created asynchronously. Add Prefer: respond-async; RDCPASS returns 202 Accepted with a job immediately.

curl https://api.rdcpass.cd/v1/fraud/reports \
  -X POST \
  -H "X-RDCPASS-Key-Id: key_live_8f2a1c0e9b" \
  -H "X-RDCPASS-Timestamp: 1790418900" \
  -H "X-RDCPASS-Nonce: 3c7e1a9d-2b4f-4d6a-8e15-9f0b7c2d4a61" \
  -H "X-RDCPASS-IV: q2Vh8Zk1pX0rT7mB" \
  -H "X-RDCPASS-Signature: b61d4e...9a07" \
  -H "Idempotency-Key: 5f0c2a8e-7d41-4b39-a6e2-1c9d8b3f7a50" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d @report.json

{
  "id": "job_4b1d9e7a2c",
  "object": "job",
  "service": "fraud_reporting",
  "status": "pending",
  "created_at": "2026-09-26T10:15:00Z",
  "result_url": "/v1/jobs/job_4b1d9e7a2c"
}

When the job completes you receive job.completed with the fraud_report in data.result, followed by fraud_report.created. You can also poll GET /v1/jobs/{job_id}.

Errors

Errors specific to this service, in the standard error format. See Errors for the full list.

Next steps

• AML & CTF Screening — Screen customers against sanctions, PEP and watchlists before they transact.
• Single, batch & async — Jobs, batches, pagination and retries in detail.
• Webhooks — Receive and verify fraud_report events.
• Going to production — The due diligence required before production keys are issued.