---
title: Messages
slug: messages
docTags: 
createdAt: 2026-10-20T15:38:32.082Z
---

Toro Payment Gateway records each nexo message that a POI exchanges with the gateway, both requests and responses. This covers payments (authorisations, completions and cancellations) and terminal management. You can read these messages through the Management API to see exactly what a terminal sent and what the gateway sent back.

Messages are read-only. The gateway creates them, and you cannot create, change or delete them.

Your role needs the `messages:read` permission.

:::BlockQuote
**Card data is redacted.** Before a message is stored, the gateway removes card data and sensitive authentication data (PAN, track data, PIN blocks and similar) to meet PCI DSS. The redacted fields are not available through this API.
:::

A **message group** holds every message for one transaction: the authorisation request and response, then any completion or cancellation. The group ID is the `SaleReferenceIdentification` that the POI sent.

## The message object

`header`, `body` and `trailer` are the nexo message converted to JSON. Element names are in PascalCase, as in the nexo specification, and code values are in snake\_case (for example `"TransactionType":"card_payment"`).

## List messages

`GET /messages`

### Examples

::::CodeDrawer{title="Example: all messages for one transaction" isResponseExpanded="true" autoGeneratedAnchorSlug="example-all-messages-for-one-transaction" legacyHash="8G3Ti2LI1KCqnSTUn3jGB"}
:::CodeblockTabsExamples
```curl
curl -G "https://mgmt-api.torogateway.dev/v1/messages" \
  -H "API-Key: <KEY>" \
  --data-urlencode "message_group_id=PUR-1760957687-204DE0FE" \
  --data-urlencode "sort_by=created_at" \
  --data-urlencode "sort_order=asc"
```
:::

:::CodeblockTabsResponses
```javascript
{
  "messages": [
    {
      "id": "ms_0199a1b2c3d47e8f9a0b1c2d3e4f5a6b",
      "account_id": "acc_...",
      "message_group_id": "PUR-1760957687-204DE0FE",
      "domain": "payment",
      "message_name": "AcceptorAuthorisationRequest",
      "purpose": "financial_authorisation_request",
      "header": {
        "MessageFunction": "financial_authorisation_request",
        "ProtocolVersion": "9.0",
        "ExchangeIdentification": 762758464801217,
        "CreationDateTime": "2025-10-20T10:54:55Z",
        "InitiatingParty": { "Identification": "50618838", "Type": "originating_poi", "Issuer": "acceptor" },
        "RecipientParty": { "Identification": "shift4", "Type": "acquirer" }
      },
      "body": {
        "Environment": {
          "Merchant": { "Identification": { "Identification": "EPASMER001" }, "CommonName": "commoner" },
          "POI": { "Identification": { "Identification": "50618838" } }
        },
        "Transaction": {
          "TransactionType": "card_payment",
          "MerchantCategoryCode": "1234",
          "SaleReferenceIdentification": "PUR-1760957687-204DE0FE",
          "TransactionDetails": { "Currency": "GBP", "TotalAmount": 5, "RequestedAmount": 5 }
        }
      },
      "trailer": {
        "ContentType": "authenticated_data",
        "AuthenticatedData": { "MACAlgorithm": { "Algorithm": "cmac_aes256" }, "MAC": "UKboQh/d+nM89Oy3D2gHKg==" }
      },
      "request_id": null,
      "response_id": "ms_0199a1b2c4e57f809a1b2c3d4e5f6a7b",
      "poi_id": "poi_...",
      "merchant_id": "mer_...",
      "acquirer": "shift4",
      "raw_acquirer_response": null,
      "created_at": "2025-10-20T10:54:55.123",
      "updated_at": "2025-10-20T10:54:55.456"
    },
    {
      "id": "ms_0199a1b2c4e57f809a1b2c3d4e5f6a7b",
      "message_name": "AcceptorAuthorisationResponse",
      "purpose": "financial_authorisation_response",
      "request_id": "ms_0199a1b2c3d47e8f9a0b1c2d3e4f5a6b",
      "response_id": null,
      "...": "..."
    }
  ],
  "pagination": { "offset": 0, "limit": 10 }
}
```
:::
::::

**Example**: authorisation requests from one POI on a given day

```curl
curl -G "https://mgmt-api.torogateway.dev/v1/messages" \
  -H "API-Key: <KEY>" \
  --data-urlencode "poi_id=poi_..." \
  --data-urlencode "message_name=AcceptorAuthorisationRequest" \
  --data-urlencode "created_at[\$gte]=2026-10-20T00:00:00"
```

**Example:&#x20;**&#x72;etrieve a message `GET /messages/{id}`

```curl
curl "https://mgmt-api.torogateway.dev/v1/messages/ms_0199a1b2c3d47e8f9a0b1c2d3e4f5a6b" \
  -H "API-Key: <KEY>"
```

This returns one message object, in the same shape as an item in the list response. If no message has that ID, the API returns `404`.

### Message and routing rules

Routing rules can read the `header`, `body` and `trailer` of the authorisation request. To find the field paths for a rule, list a transaction's `AcceptorAuthorisationRequest` messages and look at those three objects.