/meds/{medId}/analysis Endpoint

Background

/meds/{medId}/analysis is the MED analysis verdict submission endpoint for merchants. A merchant can submit an analysis verdict for a MED: accept it (ACCEPTED) or reject it (REJECTED).

Adopay validates the required evidence against the evidence requirement list for the industry the MED belongs to: only when submitting a REJECTED (reject) verdict must the required (REQUIRED) evidence be complete; no evidence files need to be uploaded when submitting an ACCEPTED (accept) verdict. The merchant only needs to submit the verdict and the analysis notes; there is no need to repeat the industry or file IDs in this request.

After the submission succeeds, the MED enters UNDER_REVIEW (under platform review) and stays there until the review result: upheld enters ACCEPTED_BY_PSP (refund executed), not upheld enters REJECTED_BY_PSP; a dispute submission may be returned by the platform to EVIDENCE_REQUIRED for resubmission after supplementing evidence. See the MED API Overview for the status flow.

Endpoint

Item	Value
Method	POST
Path	/meds/{medId}/analysis
Content-Type	application/json
Purpose	Submit the analysis verdict for a MED

Authentication

Use ES256 request signing and include all five required headers: X-Merchant-Id, X-Timestamp, X-Nonce, Digest, and Authorization. Set X-Merchant-Id to the merchant number and keyId to the key version, v1 by default. The signature is the DER-encoded ECDSA signature encoded with standard Base64. See Request Signing.

Generate the timestamp, nonce, digest, and signature placeholders for each actual request. The canonical string includes the actual path and raw query; sign again when pagination or filter parameters change.

Request Fields

Field	Location	Type	Required	Description
medId	Path	string	Yes	Unique identifier of the MED infraction report (the platform case number, medc prefix + digits), maximum length 64 characters.
analysisResult	Body	string	Yes	Analysis verdict: ACCEPTED (accept the MED) or REJECTED (reject the MED).
analysisDetails	Body	string	No	Notes or explanations attached to the analysis verdict, used to leave an audit trail, maximum length 2000 characters.

Request Examples

Approve the MED:

POST /meds/medc2874510938274639021/analysis HTTP/1.1
Content-Type: application/json
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=<REQUEST_BODY_SHA256_BASE64>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

{
  "analysisResult": "ACCEPTED",
  "analysisDetails": "Evidence clearly shows this is a fraudulent account. Transaction pattern matches known scam behavior."
}

Reject the MED:

POST /meds/medc2874510938274639021/analysis HTTP/1.1
Content-Type: application/json
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=<REQUEST_BODY_SHA256_BASE64>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

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

Response Fields

The endpoint uses the standard status, msg, and data response envelope. The response code status = 200 means the analysis was submitted successfully, and data.status is the MED business status after submission:

Requested analysisResult	Response data.status	Meaning
ACCEPTED	UNDER_REVIEW	The merchant's refund-acceptance conclusion has been submitted; under platform review.
REJECTED	UNDER_REVIEW	The merchant's dispute conclusion has been submitted; under platform review.

Field	Type	Returned	Description
status	int	Yes	Response code
msg	string	Yes	Response message corresponding to status.
data	object	On success	Analysis submission result; may be omitted when signature or protocol parsing fails.
data.medId	string	Yes	The analyzed MED ID.
data.subMerchantNo	string	Yes	The sub-merchant number that the MED belongs to; always an empty string for direct merchants; can be ignored.
data.status	string	Yes	MED business status after submission: always UNDER_REVIEW (the merchant's conclusion has been submitted and is under platform review), held until the review result (ACCEPTED_BY_PSP / REJECTED_BY_PSP).
data.analysisDetails	string	No	Analysis notes, echoing the request value.
data.dateResponse	string	Yes	Time the analysis was submitted, ISO 8601 UTC time string (yyyy-MM-ddTHH:mm:ssZ).

Response Example

The following is a successful response after submitting analysisResult = ACCEPTED:

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "medId": "medc2874510938274639021",
    "subMerchantNo": "",
    "status": "UNDER_REVIEW",
    "analysisDetails": "Evidence clearly shows this is a fraudulent account. Transaction pattern matches known scam behavior.",
    "dateResponse": "2026-06-02T09:10:00Z"
  }
}

Response Error Codes

• Response Status

Business Rules

Analysis Requirements

• The MED must be in the WAITING or EVIDENCE_REQUIRED status to submit an analysis.
• The analysis submission must be completed before the evidence submission deadline (dueTime); submissions after the deadline are rejected. A MED not submitted by the deadline is submitted by the platform on the merchant's behalf and enters platform review (non-response does not automatically establish the MED; the final outcome follows the review decision of the PSP / settlement institution).
• The caller must have access to the account associated with the MED; the MED must belong to your merchant account.
• When submitting a REJECTED (reject) verdict, every required (REQUIRED) item in the evidence requirement list must have a corresponding uploaded file; CONDITIONAL (conditionally required) items are informational only and are not enforced. This does not apply to ACCEPTED (accept) verdicts, which can be submitted directly.
• The server determines the industry from medId; the client cannot override the merchant industry.

Evidence Completeness

Evidence completeness validation applies only to REJECTED (reject) verdicts; an ACCEPTED (accept) verdict requires no evidence files and can be submitted directly. Before submitting a rejection, it is recommended to call Get Evidence Requirements and check data.complete:

• When submitting REJECTED, data.complete must be true, meaning every required (REQUIRED) item already has a corresponding uploaded file;
• Missing CONDITIONAL (conditionally required), RECOMMENDED (recommended), and OPTIONAL (optional) items do not block a rejection submission;
• When required items are missing, the rejection analysis is not recorded and the MED keeps its current status (WAITING or EVIDENCE_REQUIRED);
• After the evidence completeness validation passes, MED status, permission, and concurrency validations are still performed.

Missing evidence response example:

{
  "status": 1004,
  "msg": "Parâmetros ilegais",
  "data": {
    "code": "MISSING_REQUIRED_EVIDENCE",
    "missingEvidenceTypes": [
      "USER_ACCOUNT_RECORD",
      "TOP_UP_PURCHASE_RECORD"
    ]
  }
}

Analysis Result Notes

The analysis verdict and the MED status are two different fields; for the subsequent status flow, see the MED API Overview:

• ACCEPTED (merchant accepts the refund): After submission, the MED enters UNDER_REVIEW; when the review result upholds the MED it enters ACCEPTED_BY_PSP, followed by deduction or refund processing. The merchant accepting the refund does not mean the refund has been completed.
• REJECTED (merchant disputes): After submission, the MED enters UNDER_REVIEW; the review result upheld enters ACCEPTED_BY_PSP, and not upheld enters REJECTED_BY_PSP. A merchant dispute does not mean the MED has been finally rejected.
• Platform returns the submission: When the platform returns a dispute submission, the MED changes to EVIDENCE_REQUIRED and the funds remain frozen; the merchant can resubmit the analysis after providing the additional evidence. Refund-acceptance (ACCEPTED) submissions are not returned by the platform.

Concurrent Processing

• Only one analysis under review can exist for a MED at a time.
• If the MED already has an analysis submission under review, new submissions are rejected with a business error code.

Analysis History

• All analysis submissions are timestamped.
• User IDs are tracked for auditing.
• Analysis details are permanently stored.
• Submitted analysis records cannot be modified; after the platform returns the submission (EVIDENCE_REQUIRED), the merchant can provide additional evidence and resubmit the analysis.

Best Practices

• Get the evidence requirements and confirm that data.complete is true before submitting a REJECTED verdict (complete counts only the REQUIRED items); an ACCEPTED verdict needs no evidence files;
• Review all uploaded evidence files and their evidenceType classification;
• Provide clear, concise analysisDetails to leave an audit trail;
• Only reject when you have solid evidence that the transaction was legitimate.

---

Back to MED API Overview