Skip to main content

Outcome Reporting Endpoint

POST 
/outcome

Report the billing outcome of a Shield-cleared transaction. Reporting is one-way and asynchronous. The partner bills as normal, then reports the result.

Security​

This endpoint authenticates with a bearer token supplied in the Authorization header. Tokens are issued by MCP and scoped to a user account. Each user has one outcome token. The token may report outcomes for any active service owned by that user. The transaction's service must belong to the authenticated user.

Overview​

Each report is keyed on the uniqid returned by the JS Integration. The service is resolved from the transaction identified by uniqid. Shield verifies that the service belongs to the user authenticated by the bearer token. With outcome data, Shield can build per-service conversion baselines, separate ordinary billing friction (failed PIN, abandoned flow) from genuine attack patterns, and ground overblocking disputes in real billing history.

tip

The uniqid is the deduplication key. Re-posting for the same uniqid updates the stored outcome rather than creating a duplicate — useful when a transaction fails first and succeeds on retry. The most recent event_timestamp represents the current state, so out-of-order delivery is safe.

Behaviour:

  • The caller supplies the uniqid obtained from the JS Integration endpoint.
  • The caller reports the final billing outcome (success or failure) once it is known.
  • On failure, a failure_reason from the controlled list is required. None of these reasons imply fraud on their own.

Outcome reporting sequence:

  • Client backend bills the user as normal after a Clear decision.
  • Once the billing attempt resolves, the client backend sends POST /outcome with the uniqid and the outcome.
  • Shield acknowledges receipt and folds the outcome into its analytics asynchronously.

Request​

Responses​

Outcome report accepted.

Response Headers
    X-ResponseTime

    Total time taken to process the request, generated by the MCP Shield backend.

    Server

    Server identifier returned by the API.