---
api: 'Revolut Wallet Partner Callbacks'
---

# Fetch transaction outcomes for a transaction

Revolut calls this after detecting a Revolut-card transaction at your business. Match the
transaction from the `transaction_context` and return what it produced.

Despite using `POST`, this is a **safe lookup** with no side effects: `POST` is used only to
carry the match criteria in the body (keeping `rrn` out of URLs/logs and allowing the key to
grow). No `Idempotency-Key` is required.

**Status semantics (these drive our retry behaviour):**
- `200`: transaction matched; return the outcomes (the `passes` array may be empty).
- `202`: transaction not ready yet (settlement lag); we retry, honouring `Retry-After`.
- `404`: transaction definitively not found; we stop retrying.
- `410`: transaction existed but its outcome is void (refund/cancellation); we stop.
- `429` / `503`: temporary capacity issue; we retry, honouring `Retry-After`.

:::note
Validate Revolut's credentials (mTLS, JWS, or OAuth 2.0) and reject any unauthenticated request with `401`.
:::

:::info
See [Auto-provision transaction results](https://developer.revolut.com/docs/guides/revolut-wallet/operations/transaction-results) for matching logic and examples.
:::

## Endpoint

POST `/transaction-outcomes/search`

## Parameters

### header parameters

- `Revolut-Api-Version` (string, required)
  Contract version Revolut is calling with, e.g. `2026-07-01`.
  
  :::note
  If you receive a version you do not implement, respond with `400`.
  :::

- `Request-Id` (string, optional)
  Revolut's correlation id for this request. Echo it back in your response.

## Request body

### Attributes

- `transaction_context` (object)
    Identifiers Revolut supplies so you can match the originating transaction.
  - `transaction_context.rrn` (string)
      ISO 8583 Retrieval Reference Number of the original payment.
  - `transaction_context.merchant_id` (string)
      Card acceptor identifier (DE 42 in ISO 8583 messaging); identifies the sub-merchant for aggregators.
  - `transaction_context.transaction_at` (string)
      Timestamp of the purchase, UTC, ISO 8601.
  - `transaction_context.total` (object, optional)
      Transaction total, supplied for stronger matching. You may choose not to validate it.
    - `transaction_context.total.amount` (string)
        Decimal amount as a string (e.g. "72.40").
    - `transaction_context.total.currency` (string)
        ISO 4217 currency code (e.g. GBP, EUR, USD).

## Returns

### 200

Transaction matched. Returns the outcomes it produced.

#### Response attributes

- `passes` (array of oneOf)

### 202

Transaction accepted but its outcome is not ready yet (settlement lag). Revolut retries,
honouring `Retry-After`.

:::note
Return no body with `202`.
:::

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Malformed request or invalid body. |
| 401 | Missing or invalid Revolut credentials: no or failed mTLS certificate, an invalid JWS signature, or a missing/invalid OAuth 2.0 access token. |
| 403 | Authenticated, but the credential lacks the required scope/permission (e.g. an OAuth token without `passes.read`). |
| 404 | Transaction definitively not found. Revolut will stop retrying. |
| 410 | Transaction outcome is void (refund/cancellation). Revolut will stop retrying. |
| 429 | Rate limit exceeded. Revolut retries, honouring `Retry-After`. |
| 503 | Temporary capacity issue. Revolut retries, honouring `Retry-After`. |