---
name: transfers
description: >
  Instructs AI agents how to retrieve and delete payment transfers in Kyriba.
  Covers status monitoring by file, reference, batch, or transaction number,
  and deletion of unvalidated transfers.
version: 1.0.0
scopes:
  - payment-transaction-summary-scope
authors:
  - kyriba
tags:
  - kyriba
  - payments
  - transfers
  - 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: Transfers (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.

---

## Base Path

```
/v1/payment/transfers/status
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/payment/transfers/status` | List transfer statuses (filtered) |
| `DELETE` | `/v1/payment/transfers/{uuid}` | Delete an unvalidated/unbatched transfer |

---

## List Transfer Status

>  Pagination uses `limit`/`offset` - NOT `page.limit`/`page.offset`.

**Common filter patterns:**

```
# All transfers from a specific file
GET /v1/payment/transfers/status?filter=fileName==Oracle-payment-file-16102023.txt

# By transaction number
GET /v1/payment/transfers/status?filter=transactionNumber==HOLDACH000024

# By reference
GET /v1/payment/transfers/status?filter=reference==PAY_REF_001

# By remittance batch
GET /v1/payment/transfers/status?filter=remittance.batchId==DOMTCOM00742

# By time range (max 31 days)
GET /v1/payment/transfers/status?filter=lastACKTime=gt=2025-01-01T00:00:00.000Z;lastACKTime=lt=2025-01-31T00:00:00.000Z
```

**Pagination:**
```
GET /v1/payment/transfers/status?filter=fileName==myfile.csv&limit=100&offset=0
```

**Response:**
```json
{
  "pageMetadata": {
    "links": { "current": "...", "next": "..." },
    "total": 150,
    "count": 100,
    "limit": 100,
    "offset": 0
  },
  "results": [
    {
      "uuid": "547636a4-c07f-48fb-8577-...",
      "transactionNumber": "HOLDACH000024",
      "reference": "PAY_REF_001",
      "status": "RM",
      "file": { "uuid": "...", "name": "myfile.csv" },
      "issuer": {
        "name": "kyriba",
        "bankAccount": { "accountId": "FR3236374177852109862741628" }
      },
      "remittance": { "batchId": "DOMTCOM00742", "status": "GENERATED" },
      "lastACKTime": "2025-01-15T10:30:00.000Z"
    }
  ]
}
```

---

## Filterable Fields

```
transactionNumber, uuid, fileName, reference,
remittanceIdentifier1, remittanceIdentifier2,
repository.code, remittance.batchId, lastACKTime,
status, endToEndId
```

** Filter restrictions:**
- `status` and `endToEndId` - exact match only (`==`). Wildcards not supported.
- `lastACKTime` - only `=gt=`, `=lt=`, `=ge=`, `=le=` with ISO 8601 datetime (`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`)
- `lastACKTime` max range = **31 days**. Exceeding returns an error.
- `fileName` filter: max **20,000 transfers** per file. Exceeding this limit disables the filter.

## Two Status Fields

Each transfer has two distinct status fields:

| Field | Meaning | Example |
|---|---|---|
| `status` | Top-level transfer processing status (e.g. `RM` = Remittance created) | `"RM"` |
| `remittance.status` | Current state of the remittance batch the transfer belongs to | `"GENERATED"` |

**`remittance.status` values and next actions:**

| Status | Next Action |
|---|---|
| `CONSTITUTED` | Generate the bank file |
| `GENERATED` | Monitor the file approval / Transmit |
| `TO_BE_DELETED` | Delete the remittance |
| `TO_BE_MODIFIED` | Modify the remittance |
| `PUSHED_TO_COMMUNICATION_CHANNEL` | Wait for answer from bank |
| `TRANSMITTED` | None - processing complete |

---

## Delete a Transfer

Only transfers that are **not yet validated or batched** can be deleted.

```
DELETE /v1/payment/transfers/{uuid}
```

Use with Transfers Status to identify deletable transfers first:
```
GET /v1/payment/transfers/status?filter=fileName==myfile.csv
-> find UUIDs with deletable status
-> DELETE /v1/payment/transfers/{uuid} for each
```

---

## Critical Rules

1. Pagination is `limit`/`offset` - NOT `page.limit`/`page.offset`
2. `lastACKTime` max range = 31 days - always validate before sending
3. `status` and `endToEndId` are exact-match only - no wildcards
4. `fileName` filter fails silently above 20,000 transfers - use `remittance.batchId` for large batches
5. Only unvalidated/unbatched transfers can be deleted

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Success |
| `204` | Transfer deleted |
| `400` | Invalid filter (e.g. wildcard on status, lastACKTime range > 31 days) |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Transfer not found |
| `409` | Transfer cannot be deleted (already validated or batched) |

---

## OpenAPI Spec & Postman Collection

- OpenAPI: `https://developer.kyriba.com/static/apis/transfers/transfers.yaml`
- Postman: `https://developer.kyriba.com/static/apis/payment-transaction-summary/payment-transaction-summary-postman-collection.json`