Submit MED Analysis Result

Submit your analysis decision for a MED dispute. You can accept the dispute (ACCEPTED) and specify the fraud type, or reject it (REJECTED). Accepted disputes trigger the refund process workflow.

POSThttps://api.somossimpay.com.br/v3/meds/{med_id}/analysis

curl --request POST \
  --url 'https://api.somossimpay.com.br/v3/meds/{med_id}/analysis' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "analysis_result": "ACCEPTED",
  "fraud_type": "FRAUDULENT_ACCOUNT",
  "analysis_details_user": "Evidence clearly shows this is a fraudulent account. Transaction pattern matches known scam behavior."
}'

Response200

{
  "pixmed_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "IN_PROCESSING",
  "analysis_details_user": "Evidence clearly shows this is a fraudulent account. Transaction pattern matches known scam behavior.",
  "date_response_user": "2026-06-02T14:30:00Z"
}

Endpoint

POST /v3/meds/{med_id}/analysis

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo

Path Parameters

Parameter	Type	Description	Example
med_id	String	The unique identifier of the MED infraction report	550e8400-e29b-41d4-a716-446655440000

Body Details

Field	Type	Description	Required or Optional
analysis_result	String	Your decision on the dispute: `ACCEPTED` or `REJECTED`	required
fraud_type	String	Type of fraud identified (required when analysis_result is `ACCEPTED`)	optional
analysis_details_user	String	Additional notes or explanation for your analysis decision	optional

Valid fraud_type values (required when accepting):

IDEOLOGICAL_FALSEHOOD - False information or forged documents
SHELL_ACCOUNT - Account used as front for fraudulent activities
FRAUDULENT_ACCOUNT - Account opened with fraudulent intent
OTHER - Other types of fraud not covered above
UNKNOWN - Fraud type not identified

Request Examples

Accept dispute with fraud type:

{
  "analysis_result": "ACCEPTED",
  "fraud_type": "FRAUDULENT_ACCOUNT",
  "analysis_details_user": "Evidence clearly shows this is a fraudulent account. Transaction pattern matches known scam behavior."
}

Reject dispute:

{
  "analysis_result": "REJECTED",
  "analysis_details_user": "Transaction was legitimate. Customer confirmed receipt of goods and services."
}

Accept with shell account:

{
  "analysis_result": "ACCEPTED",
  "fraud_type": "SHELL_ACCOUNT",
  "analysis_details_user": "Multiple transfers detected. Account shows characteristics of money mule operation."
}

Response Details

{
  "pixmed_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "IN_PROCESSING",
  "analysis_details_user": "Evidence clearly shows this is a fraudulent account. Transaction pattern matches known scam behavior.",
  "date_response_user": "2026-06-02T14:30:00Z"
}

{
  "pixmed_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "REJECTED_BY_USER",
  "analysis_details_user": "Transaction was legitimate. Customer confirmed receipt of goods and services.",
  "date_response_user": "2026-06-02T14:30:00Z"
}

Field	Type	Description
pixmed_id	String	MED ID that was analyzed
status	String	New status: `IN_PROCESSING` for accepted, `REJECTED_BY_USER` for rejected
analysis_details_user	String	Your analysis notes
date_response_user	DateTime	Timestamp when analysis was submitted (ISO 8601 format)

Error Responses

HTTP Code	Error Message	Description
400	PIXMED is not in a valid state for analysis. Current status: {status}	MED must be in WAITING status to accept analysis
400	This MED is already being processed	Another analysis is already in progress for this MED
400	fraud_type is required when accepting	You must specify fraud type when analysis_result is ACCEPTED
400	PIXMED is not in a valid state for analysis. Enrichment is False	MED must have enrichment enabled to accept analysis
400	PIXMED is not in a valid state for analysis. Creator PSP is {ISPB}	Cannot analyze MEDs created by your own institution
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token
404	Med not found	The specified MED ID does not exist or you don't have access to it
422	Validation error	Request validation failed. Check required fields and data types

Business Rules

Analysis Requirements:

MED must be in WAITING status to submit analysis
You must have Permissions.PixMed.ANALYZE scope
You must have access to the account associated with the MED
MED must belong to your company
MED must have enrichment enabled (is_enrichment=True)
Cannot analyze MEDs created by your own institution (creator_psp must be different)

Analysis Results:

ACCEPTED:

Triggers the refund process workflow
Creates a processing record (PixMedInProcessing)
Sends analysis to processing queue for automated handling
Status changes to IN_PROCESSING
Must include fraud_type to categorize the dispute
System will attempt to process the refund automatically

REJECTED:

Dispute is denied immediately
Status changes to REJECTED_BY_USER
No refund will be processed
Analysis is recorded for audit purposes
Dispute is considered closed

Fraud Type Classification:

IDEOLOGICAL_FALSEHOOD: Used for cases involving fake documents, false declarations, or forged information
SHELL_ACCOUNT: Accounts used as intermediaries in money laundering schemes (mule accounts)
FRAUDULENT_ACCOUNT: Accounts opened with fraudulent intent or stolen identity
OTHER: Any fraud type not covered by specific categories
UNKNOWN: When fraud is confirmed but specific type cannot be determined

Status Flow:

WAITING → (Submit Analysis)
  ├─→ IN_PROCESSING (if ACCEPTED)
  └─→ REJECTED_BY_USER (if REJECTED)

Concurrent Processing:

Only one analysis can be in progress at a time per MED
System checks for existing PixMedInProcessing records
If another analysis is already processing, request is rejected with 400 error

Analysis History:

All analysis submissions are recorded with timestamp
User ID is tracked for audit purposes
Analysis details are permanently stored
Cannot modify analysis after submission

Best Practices:

Review all uploaded evidence files before submitting analysis
Provide clear, concise analysis_details_user for audit trail
Select most specific fraud_type when accepting disputes
Reject only when you have strong evidence transaction was legitimate

curl --request POST \
  --url 'https://api.somossimpay.com.br/v3/meds/{med_id}/analysis' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "analysis_result": "ACCEPTED",
  "fraud_type": "FRAUDULENT_ACCOUNT",
  "analysis_details_user": "Evidence clearly shows this is a fraudulent account. Transaction pattern matches known scam behavior."
}'

Response200

{
  "pixmed_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "IN_PROCESSING",
  "analysis_details_user": "Evidence clearly shows this is a fraudulent account. Transaction pattern matches known scam behavior.",
  "date_response_user": "2026-06-02T14:30:00Z"
}