---
name: payment-transaction-summary
description: >
  Instructs AI agents how to query transaction-level details for routed bulk
  payment files in Kyriba. Covers individual transaction status, counterparty,
  remittance, accounting, and custom field data per payment file.
version: 1.0.0
scopes:
  - payment-transaction-summary-scope
authors:
  - kyriba
tags:
  - kyriba
  - payments
  - transactions
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Payment Transaction Summary

---

## Required Kyriba Permission

```
payment-transaction-summary-scope
```

This is a Kyriba access permission — not an OAuth scope parameter. Do NOT add `scope=` to the token request.

---

## What is the Payment Transaction Summary?

Read-only. Exposes transaction-level detail for each payment inside a routed bulk payment file. Use to review individual transaction status, issuer, counterparty, remittance info, and accounting data after a file has been processed.

---

## Base URL

```
https://api.demo.kyriba.com/api/payments/payments-routing/payment-transaction-summary-details/v2
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/payments/payments-routing/payment-transaction-summary-details/v2/details` | List transactions |
| `GET` | `/api/payments/payments-routing/payment-transaction-summary-details/v2/details/documented-fields` | List documented field names |
| `GET` | `/api/payments/payments-routing/payment-transaction-summary-details/v2/details/documented-fields/{field}` | Get valid enum values (currently: `status`) |
| `GET` | `/api/payments/payments-routing/payment-transaction-summary-details/v2/details/searchable-fields` | List filterable fields |

---

## Pagination

Uses flat `offset` / `limit`. Response envelope key: **`pageMetadata`** (not `metadata`).

```json
{
  "pageMetadata": { "total": 1000, "count": 100, "limit": 100, "offset": 0,
    "links": { "current": "...", "next": "..." }
  },
  "results": [ ... ]
}
```

---

## Example Requests

**List transactions for a file:**
```
GET .../details?filter=file.uuid==3fa85f64-5717-4562-b3fc-2c963f66afa6&offset=0&limit=100
```

**GET list response:**
```json
{
  "metadata": {
    "pageLimit": 100,
    "pageOffset": 0,
    "pageResults": 2,
    "numberOfTotalResults": 2
  },
  "results": [ ... ]
}
```
> Response key is always `results`. Stop paginating when `len(results) < pageLimit`.

**List EXECUTED transactions:**
```
GET .../details?filter=status.code==EXECUTED&sort=transactionDate&offset=0&limit=100
```

---

## Key Response Fields

| Field | Description |
|---|---|
| `file.uuid` | Payment file UUID |
| `file.name` | File name |
| `transactionDate` | `YYYY-MM-DD` |
| `endToEndId` | End-to-end reference |
| `amount` | Transaction amount |
| `currency` | ISO currency code |
| `status.code` | Use `/documented-fields/status` for valid values |
| `status.lastAck` | Bank ACK code |
| `status.lastAckTime` | ISO 8601 timestamp |
| `status.UETR` | SWIFT unique reference |
| `issuer.name` | Ordering customer |
| `issuer.bankAccount.accountId` | Issuer IBAN |
| `issuer.bankIdentifier` | Issuer BIC |
| `counterparty.name` | Beneficiary name |
| `counterparty.bankAccount.accountId` | Beneficiary IBAN |
| `counterparty.bankIdentifier` | Beneficiary BIC |
| `remittanceInfo` | Remittance information |
| `reason.code` | Reason code (e.g. `FR003`) |
| `reason.description` | Reason description |
| `accountingInformation[]` | Accounting entries |
| `customFields[]` | `{ name, value }` pairs |

---

## Critical Rules

1. No single-record GET - all data via list with filters
2. Filter by `file.uuid` when looking up a specific payment file's transactions
3. Response key is `pageMetadata` - not `metadata`
4. Pagination: flat `offset`/`limit` - not `page.offset`/`page.limit`

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Success |
| `400` | Invalid filter |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | No data found |

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/payment-transaction-summary/payment-transaction-summary.yaml`