---
name: payment-files-status
description: >
  Instructs AI agents how to check the status of uploaded bulk payment files
  (routed files) in Kyriba. Provides Kyriba processing status and bank
  acknowledgement details. Read-only - list only.
version: 1.0.0
scopes:
  - payment-file-scope
authors:
  - kyriba
tags:
  - kyriba
  - payments
  - payment-files-status
  - 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 Files Status

---

## Required Kyriba Permission

```
payment-file-scope
```

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

>  Note: scope is `payment-file-scope` (singular), not `payment-files-scope`.

---

## What is This API?

Once a payment file is uploaded and routed in Kyriba, this API returns its processing status plus any bank acknowledgement details (ACK/NACK, rejected transfers, etc.).

---

## Base Path

```
/v1/payment/payment-files
```

>  Note the double `payment` in the path: `/v1/payment/payment-files` - not `/v1/payment-files`.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/payment/payment-files` | List payment file statuses |

> This API is **read-only** - no create, update, or delete.

---

## Filterable Fields

```
fileName, uuid
```

>  **Only `fileName` and `uuid` are sortable.** Sorting by `creationDateTime` returns `400`.

---

## Example Requests

**Get status by file name:**
```
GET /v1/payment/payment-files?filter=fileName==2025-07-08T12:00:00-Gr1-Tr1-PAYMENTS.csv
```

**Get status by uuid:**
```
GET /v1/payment/payment-files?filter=uuid==xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

**List recent files (paginated):**
```
GET /v1/payment/payment-files?page.limit=50&page.offset=0&sort=-uuid
```

**List response:**
```json
{
  "metadata": {
    "links": { "current": "...", "next": "..." },
    "pageResults": 10,
    "numberOfTotalResults": 4093,
    "pageLimit": 10,
    "pageOffset": 0
  },
  "results": [
    {
      "uuid": "...",
      "fileName": "P100009.VO320",
      "creationDateTime": "2022-02-08T19:03:32Z",
      "status": "TRANSMITTED",
      "nextAction": "NONE",
      "lastACK": {
        "kyribaACK": "(1) Sent to the bank",
        "bankACK": null,
        "lastACKTime": "2022-02-08T19:11:16Z"
      }
    }
  ]
}
```

>  Metadata uses non-standard field names: `numberOfTotalResults`, `pageLimit`, `pageOffset` - not `total`, `limit`, `offset`.

**Known `status` values:** `UPLOADED`, `GENERATED`, `TRANSMITTED`, `REJECTED_INCORRECT_DATA`

**Known `nextAction` values:** `NONE`, `RELEASE_FILE`, `SIGN_LEVEL1`, `PROCESS_AGAIN`

**Get detailed log for a file:**
```
GET /v1/payment/payment-files/{uuid}/log
```
```json
{
  "uuid": "...",
  "status": "TRANSMITTED",
  "log": "APPROVAL WORKFLOW:\n...\nACKNOWLEDGEMENT:\n..."
}
```
> `lastACK` is in the **list response** only - the `/log` endpoint returns `uuid`, `status`, and `log` text only.
```

---

## Relationship to Other Payment APIs

| API | What it tracks |
|---|---|
| **Payment Files Status** (this skill) | Routed payment file lifecycle (Kyriba -> Bank) |
| **Transfers** | Individual transfer-level status and remittance details |

Use Payment Files Status for bulk file-level monitoring. Use Transfers for individual payment tracking.

---

## Error Reference

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

---

## OpenAPI Spec & Postman Collection

- OpenAPI: `https://developer.kyriba.com/static/apis/payment-files-status/payment-files-status.yaml`
- Postman: `https://developer.kyriba.com/static/apis/payment-files-status/payment-files-status-postman-collection.json`