Create Report

Submit a fraud or complaint report on behalf of your user (e.g. tracking a transaction, reporting stolen funds, or flagging fraud).

POST /v1/reports

Required Permission: report:create

Request Body:

Field	Type	Required	Description
complaintType	string	Yes	track_transaction, stolen_funds, or fraud
name	string	Yes	Name of the person filing the report
phoneNumber	string	Conditional	Reporter's phone number (required unless walletAddress provided)
walletAddress	string	Conditional	Reporter's wallet address (required unless phoneNumber provided)
sessionReference	string	No	Related payment reference, if applicable
fraudsterWalletAddress	string	No	Wallet address of the alleged fraudster
description	string	No	Free-text details of the complaint (max 5000 chars)

Example: Report Stolen Funds

POST /v1/reports
{
  "complaintType": "stolen_funds",
  "name": "Adaeze Nwosu",
  "phoneNumber": "2348012345678",
  "walletAddress": "TDrhiGeJ11zNStTLhcJt4CvqSwyUVbHPZR",
  "fraudsterWalletAddress": "TXn9d8f7e6c5b4a3928170fedcba0987654",
  "description": "Funds were sent to the wrong address after a phishing link."
}

Response: 201 Created

{
  "success": true,
  "data": {
    "report": {
      "id": 42,
      "reportId": "RPT-7N4VFR",
      "apiKeyId": 7,
      "merchantId": "merchant_001",
      "sessionReference": null,
      "complaintType": "stolen_funds",
      "name": "Adaeze Nwosu",
      "phoneNumber": "2348012345678",
      "walletAddress": "TDrhiGeJ11zNStTLhcJt4CvqSwyUVbHPZR",
      "fraudsterWalletAddress": "TXn9d8f7e6c5b4a3928170fedcba0987654",
      "description": "Funds were sent to the wrong address after a phishing link.",
      "status": "pending",
      "confirmer": null,
      "adminNotes": null,
      "createdAt": "2026-07-29T10:15:00.000Z",
      "updatedAt": "2026-07-29T10:15:00.000Z"
    }
  }
}

Error Cases:

• Missing both phoneNumber and walletAddress: 400 - At least one of phoneNumber or walletAddress must be provided
• Validation failed (invalid/missing fields): 400