/meds/{medId}/analysis

Background

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

Adopay validates the required evidence against the Evidence Requirements for the industry the MED belongs to: only a REJECTED verdict requires all REQUIRED evidence to be complete; an ACCEPTED verdict requires no evidence files. The partner only submits the verdict and analysis notes — there is no need to repeat the sub-merchant number, industry, or file IDs in this request.

After a successful submission, 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 status transitions.

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 partner's top-level merchant number and keyId to the key version, v1 by default. The signature is a 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's business status after submission:

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

Field	Type	Always Returned	Description
status	int	Yes	Response code
msg	string	Yes	Corresponds to status
data	object	On success	Analysis submission result; may be omitted when the request fails at signature verification or protocol parsing.
data.medId	string	Yes	The analyzed MED ID.
data.subMerchantNo	string	Yes	Sub-merchant number that owns the MED (a partner-model extension field, not present in responses of the direct merchant API).
data.status	string	Yes	MED business status after submission: always UNDER_REVIEW (the partner's conclusion has been submitted and the platform is reviewing it), 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 the success response after submitting analysisResult = ACCEPTED:

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "medId": "medc2874510938274639021",
    "subMerchantNo": "24922653000123",
    "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 partner'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 a sub-merchant under your partner account.
• When submitting a REJECTED verdict, all REQUIRED evidence in the evidence requirements must already have corresponding files uploaded; CONDITIONAL evidence is informational only and is not part of the mandatory validation. This does not apply to an ACCEPTED verdict, which can be submitted directly.
• The server resolves the sub-merchant and industry from medId; client-side overrides of the merchant industry are not accepted.

Evidence Completeness Validation

Evidence completeness is validated only for REJECTED verdicts; an ACCEPTED verdict can be submitted directly without uploading evidence files. Before submitting a rejection, it is recommended to call Get Evidence Requirements and check data.complete:

• For a REJECTED submission, data.complete must be true, meaning all REQUIRED evidence has corresponding files uploaded;
• Missing CONDITIONAL, RECOMMENDED, or OPTIONAL evidence does not block a rejection;
• When required evidence is missing, the rejection analysis is not recorded and the MED keeps its current status (WAITING or EVIDENCE_REQUIRED);
• After the evidence completeness check 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 Outcomes

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

• ACCEPTED (the partner agrees to 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 partner agreeing to the refund does not mean the refund has been completed.
• REJECTED (the partner disputes): After submission the MED enters UNDER_REVIEW; the review result upheld enters ACCEPTED_BY_PSP, and not upheld enters REJECTED_BY_PSP. The partner disputing does not mean the MED has been finally rejected.
• Returned by the platform: When the platform returns the dispute submission, the MED changes to EVIDENCE_REQUIRED with funds kept frozen; the partner can supplement evidence and resubmit the analysis. A refund-acceptance (ACCEPTED) submission is never returned by the platform.

Concurrent Processing

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

Analysis History

• All analysis submissions are timestamped.
• Caller identifiers are tracked for auditing.
• Analysis details are permanently stored.
• A submitted analysis record cannot be modified; after the platform returns it (EVIDENCE_REQUIRED), evidence can be supplemented and the analysis resubmitted.

Best Practices

• Query the evidence requirements and confirm data.complete is true before submitting a REJECTED verdict (complete counts only REQUIRED evidence); an ACCEPTED verdict requires 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