--- name: payment-automation description: > Instructs AI agents how to build applications or scripts that interact with the Kyriba Payment Automation API - covering data preparation, CSV upload, import/batching process execution, status polling, transfer monitoring, and webhook-based flows. Applicable to UI apps, CLI tools, Python scripts, or any HTTP client. version: 1.0.0 scopes: - files-scope - process-template-scope - payment-transaction-summary-scope authors: - kyriba tags: - kyriba - payments - automation - finance - api - ui --- > **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 Automation > This skill is pre-configured for the Kyriba DEMO environment. > To use it with your own Kyriba instance, see the **Customization** section at the bottom. --- ## CREDENTIALS ``` CLIENT_ID= CLIENT_SECRET= TOKEN_URL=https://auth.demo.kyriba.com/oauth/token BASE_URL=https://api.demo.kyriba.com/api ``` **Ask the user only for `CLIENT_ID` and `CLIENT_SECRET`.** `TOKEN_URL` and `BASE_URL` are already set for the demo environment - do not ask for them. **Demo template references (hardcoded, do not change for demo):** ``` IMPORT_TEMPLATE_REF=DEMO_PY_AP BATCH_TEMPLATE_REF=DEMO_BATCH_API ``` --- ## Flow ``` 1. Prepare CSV payment data 2. Upload CSV -> fileId 3. Run import template (DEMO_PY_AP) with fileId -> taskId -> poll until Complete/Warning 4. Run batching template (DEMO_BATCH_API) with no fileId -> taskId -> poll until Complete 5. [Approval - manual in Kyriba UI, not automatable via API] 6. [Bank processing - external, nothing to do] 7. Check payment/transfer status by fileName or batchId ``` --- ## CSV Payment Data Format **DO NOT guess or invent this format.** Use exactly: ``` ;{DDMMYYYY};{amount};;{processEntryType};{reference}\r\n ``` **Field breakdown:** ``` ; {DDMMYYYY} ; {amount} ; ; {processEntryType} ; {reference} ^ ^ ^ ^ | | | └─ empty category field (not required for this flow) | | └─ amount | └─ date (DDMMYYYY) └─ empty account field (template uses its configured default account) ``` **Rules:** - Date is `DDMMYYYY` - NOT `YYYY-MM-DD`, NOT ISO format - No header row - Line ending is `\r\n` (CRLF), not `\n` - `Content-Type: text/plain` on upload - NOT `multipart/form-data`, NOT JSON **Process entry type for demo:** `ST_PET` To find your production value: **Kyriba UI -> Settings -> Process Entry Types** **Example (3 payments, date 22 July 2025, amount 10):** ``` ;22072025;10;;ST_PET;PAYMENT_REF_1\r\n ;22072025;10;;ST_PET;PAYMENT_REF_2\r\n ;22072025;10;;ST_PET;PAYMENT_REF_3\r\n ``` **Filename convention:** ``` {YYYY-MM-DD}T{HH:MM:SS}-Gr{groupNum}-Tr{count}-{reference}.csv ``` Example: `2025-07-22T12:16:27-Gr1-Tr3-PAYMENT_TEST.csv` --- ## Endpoints All requests go to `BASE_URL = https://api.demo.kyriba.com/api` | Step | Method | Path | Notes | |------|--------|------|-------| | Upload data | POST | `/v1/data?fileName={name}` | Body: CSV text, `Content-Type: text/plain` | | Run import | POST | `/v1/process-templates/DEMO_PY_AP/run?fileIds={fileId}` | `fileIds` as query param, not in body | | Run batching | POST | `/v1/process-templates/DEMO_BATCH_API/run` | No fileIds | | Poll task | GET | `/v1/process-templates/{taskId}/status` | | | Payment files | GET | `/v1/payment/payment-files?filter=fileName=={name}` | | | Transfer status (by file) | GET | `/v1/payment/transfers/status?filter=fileName=={name}` | | | Transfer status (by ref) | GET | `/v1/payment/transfers/status?filter=reference=={ref};fileName=={name}*` | Transaction level | | Transfer status (by batch) | GET | `/v1/payment/transfers/status?filter=remittance.batchId=={id}` | Webhook flow | --- ## API Response Schemas **Upload response (`POST /v1/data`):** ```json { "fileId": "abc123-def456" } ``` Extract `response["fileId"]`. **Run template response (`POST /v1/process-templates/{ref}/run`):** > Response is always an **array**. Extract `response[0]["taskId"]`. ```json [ { "taskId": "abc123-def456", "status": "Pending" } ] ``` **Poll task response (`GET /v1/process-templates/{taskId}/status`):** ```json { "taskId": "abc123-def456", "status": "Complete" } ``` --- ## Critical Rules 1. **Data upload** - `Content-Type: text/plain` (not JSON, not multipart) 2. **`fileIds`** - query parameter on `/run`, not in body 3. **Run response** - always an **array**: extract `response[0]["taskId"]` 4. **Task completion** - check for `"Complete"` OR `"Warning"` (both = finished) 5. **Batching run** - same `/run` endpoint but **no `fileIds`** param 6. **Multiple payment groups** - upload one CSV per group sequentially, each returns its own `fileId` and `taskId`; do not pass multiple fileIds in a single call 7. **Transfer status** - `fileName==` for batch polling; `reference==` for transaction level; `remittance.batchId==` for webhook flow --- ## Task Status Values `Pending` -> `In progress` -> `Complete` | `Warning` | `Failed` - `Warning` = finished with some rejections. Show user which references were rejected. - Poll interval: 5 seconds, max 30 attempts. --- ## Error Handling | HTTP Status | Meaning | Action | |---|---|---| | `400 Bad Request` | Invalid request body or parameters | Log response body for details, fix input | | `401 Unauthorized` | Invalid or expired token | Re-authenticate, retry once with alternate token scheme (`Bearer` ↔ `token`) | | `403 Forbidden` | Missing API scope | Check that your API client has the required scopes (`files-scope`, `process-template-scope`, `payment-transaction-summary-scope`) | | `404 Not Found` | Wrong path or template ref not found | Verify template reference exists in Kyriba UI | | `429 Too Many Requests` | Rate limit exceeded | Wait until `Kyriba-Customer-Rate-Limit-Reset` header value, then retry | | `5xx Server Error` | Kyriba server error | Retry with exponential backoff (1s, 2s, 4s); log `taskId` for support | --- ## Transfer Status Response ```json { "results": [ { "transactionNumber": "COMDOMS003665", "status": "RM", "reference": "PAYMENT_REF_1", "nextAction": "...", "remittance": { "batchId": "DOMTCOM00742", "status": "GENERATED" } } ] } ``` **Remittance status -> next action mapping:** | 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 | | `TRANSMITTED` | None - processing complete | --- ## If Building a UI Application Suggested views and their data sources: | View | API call | |------|----------| | Upload form | User input -> generate CSV -> `POST /v1/data` | | Import status | Poll `GET /v1/process-templates/{taskId}/status` every 5s | | Transfer list | `GET /v1/payment/transfers/status?filter=fileName=={name}` | | Batch dashboard | `GET /v1/payment/transfers/status?filter=remittance.batchId=={id}` | | Remittance next action | Map `remittance.status` using table above | Approval step is manual in Kyriba UI - surface it as a user action prompt, not an API call. --- ## Notes - Webhook flow: subscribe to `batch_status_changed`, extract `batchId` from notification payload - Multiple payment groups = upload a separate CSV per group, each with its own `fileId` and `taskId` --- ## Customization This skill is pre-configured for the Kyriba DEMO environment. Feel free to update this skill file to match your own setup: 1. **Credentials** - replace `TOKEN_URL` and `BASE_URL` with values from your Kyriba administrator. Production `TOKEN_URL` follows the pattern: `https://auth.{your-instance}.kyriba.com/oauth/token` 2. **Template references** - replace `DEMO_PY_AP` and `DEMO_BATCH_API` with your instance's codes. To find them: **Kyriba UI -> Settings -> Process Templates** 3. **Process entry type** - replace `ST_PET` with your configured value. To find it: **Kyriba UI -> Settings -> Process Entry Types** All values above come from your Kyriba instance configuration.