API documentation

Refund

A full or partial Промет Рефундација of a receipt BokaPOS issued. You name which lines and how much is returned; BokaPOS verifies the original, writes the reference and, when cash is returned, immediately issues the copy with the signature line.

Updated: 29 August 2026 · Contract version 1.0.0

Rules

The source is always a receipt BokaPOS issued (original.source: BOKA, fiscalDocumentId) of type Промет Продаја, on the same taxpayer and premise. Refunding another ESIR's receipt is not supported, because how much was already returned cannot be verified.
Every refund item points to a line of the original receipt (originalLineIndex, zero-based) and must repeat its name, unit, price, labels and GTIN. The quantity may be smaller (partial refund); the sum of every refund of that line never exceeds the original quantity.
buyer.id is mandatory: the regulations require buyer identification on every refund (for example 20: identity card number or 10: PIB).
payments are the returned funds; the sum must equal the refunded items. If any payment is CASH, BokaPOS immediately issues the Копија Рефундације with the customer-signature line, as the regulations require.
A refund is never blocked by licensing: an issued receipt can always be unwound.

Request

POST /v1/refund-workflows

curl -X POST "https://api.bokapos.rs/v1/refund-workflows" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-4127-refund-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127-R1",
  "original": {
    "source": "BOKA",
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761"
  },
  "cashier": {
    "id": "web-shop"
  },
  "buyer": {
    "id": "20:001234567"
  },
  "items": [
    {
      "originalLineIndex": 0,
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CARD",
      "amount": 8990
    }
  ]
}'

Response

201 Created

{
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127-R1",
  "status": "COMPLETED",
  "original": {
    "source": "BOKA",
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
    "pfrNumber": "JWX4K9PL-JWX4K9PL-1042",
    "pfrTime": "2026-09-01T10:15:32.483+02:00",
    "invoiceType": "NORMAL",
    "transactionType": "SALE"
  },
  "refund": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "idempotencyKey": "order-4127-refund-1",
    "clientReference": "ORDER-4127-R1",
    "invoiceType": "NORMAL",
    "transactionType": "REFUND",
    "cashierId": "web-shop",
    "buyerId": "20:001234567",
    "buyerDetails": null,
    "status": "FISCALIZED",
    "fiscalized": true,
    "failureCode": null,
    "retryable": false,
    "pfr": {
      "invoiceNumber": "JWX4K9PL-JWX4K9PL-1045",
      "sdcTime": "2026-09-01T10:15:32.483+02:00",
      "requestedBy": "JWX4K9PL",
      "signedBy": "JWX4K9PL",
      "transactionTypeCounter": 900,
      "totalCounter": 1045,
      "invoiceCounterExtension": "ПР",
      "totalAmount": 8990,
      "totalTax": 890.9009,
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1045\nБројач рачуна:                900/1045ПР\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
    },
    "receipt": {
      "textUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/official-text",
      "jsonUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/canonical-json",
      "pdfA4Url": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-a4",
      "pdf80mmUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-80mm",
      "pdf58mmUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-58mm",
      "previewImageUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/preview-png",
      "qrImageUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/qr-svg",
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "preferredPaperFormat": "a4"
    },
    "reference": {
      "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
      "pfrNumber": "JWX4K9PL-JWX4K9PL-1042",
      "pfrTime": "2026-09-01T10:15:32.483+02:00"
    },
    "createdAt": "2026-09-01T14:40:04.310Z",
    "updatedAt": "2026-09-01T08:15:32.611Z"
  },
  "cashRefundCopy": null,
  "failureCode": null,
  "createdAt": "2026-09-01T14:40:04.300Z",
  "updatedAt": "2026-09-01T14:40:05.120Z"
}

`status`	Meaning	What to do
`COMPLETED`	the refund (and the copy, if needed) is fiscalized	store `refund.id` and `refund.pfr.*`; if `cashRefundCopy` exists, print it for signature
`REFUND_PENDING`	the refund was not sent (V-PFR unavailable), HTTP 503	repeat the same request with the same key
`REFUND_OUTCOME_UNKNOWN`	the refund was sent, the response did not arrive, HTTP 503	do not retry; poll `GET /v1/operations/{refund.id}`
`COPY_PENDING`, `COPY_OUTCOME_UNKNOWN`	the refund exists, the copy is not finished, HTTP 503	repeat with the same key (pending) or wait (unknown); the refund is already valid
`FAILED`	the V-PFR rejected; `failureCode` and `refund.pfrRejection` say why	fix and send with a new key

Cash refund

POST /v1/refund-workflows

curl -X POST "https://api.bokapos.rs/v1/refund-workflows" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-4127-refund-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127-R1",
  "original": {
    "source": "BOKA",
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761"
  },
  "cashier": {
    "id": "web-shop"
  },
  "buyer": {
    "id": "20:001234567"
  },
  "items": [
    {
      "originalLineIndex": 0,
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CASH",
      "amount": 8990
    }
  ]
}'

201 Created

{
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127-R1",
  "status": "COMPLETED",
  "original": {
    "source": "BOKA",
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
    "pfrNumber": "JWX4K9PL-JWX4K9PL-1042",
    "pfrTime": "2026-09-01T10:15:32.483+02:00",
    "invoiceType": "NORMAL",
    "transactionType": "SALE"
  },
  "refund": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "idempotencyKey": "order-4127-refund-1",
    "clientReference": "ORDER-4127-R1",
    "invoiceType": "NORMAL",
    "transactionType": "REFUND",
    "cashierId": "web-shop",
    "buyerId": "20:001234567",
    "buyerDetails": null,
    "status": "FISCALIZED",
    "fiscalized": true,
    "failureCode": null,
    "retryable": false,
    "pfr": {
      "invoiceNumber": "JWX4K9PL-JWX4K9PL-1045",
      "sdcTime": "2026-09-01T10:15:32.483+02:00",
      "requestedBy": "JWX4K9PL",
      "signedBy": "JWX4K9PL",
      "transactionTypeCounter": 900,
      "totalCounter": 1045,
      "invoiceCounterExtension": "ПР",
      "totalAmount": 8990,
      "totalTax": 890.9009,
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1045\nБројач рачуна:                900/1045ПР\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
    },
    "receipt": {
      "textUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/official-text",
      "jsonUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/canonical-json",
      "pdfA4Url": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-a4",
      "pdf80mmUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-80mm",
      "pdf58mmUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-58mm",
      "previewImageUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/preview-png",
      "qrImageUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/qr-svg",
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "preferredPaperFormat": "a4"
    },
    "reference": {
      "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
      "pfrNumber": "JWX4K9PL-JWX4K9PL-1042",
      "pfrTime": "2026-09-01T10:15:32.483+02:00"
    },
    "createdAt": "2026-09-01T08:15:31.902Z",
    "updatedAt": "2026-09-01T08:15:32.611Z"
  },
  "cashRefundCopy": {
    "id": "6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "idempotencyKey": "order-4127-refund-1:copy",
    "clientReference": "COPY-ORDER-4127-R1",
    "invoiceType": "COPY",
    "transactionType": "REFUND",
    "cashierId": "web-shop",
    "buyerId": "20:001234567",
    "buyerDetails": null,
    "status": "FISCALIZED",
    "fiscalized": true,
    "failureCode": null,
    "retryable": false,
    "pfr": {
      "invoiceNumber": "JWX4K9PL-JWX4K9PL-1046",
      "sdcTime": "2026-09-01T10:15:32.483+02:00",
      "requestedBy": "JWX4K9PL",
      "signedBy": "JWX4K9PL",
      "transactionTypeCounter": 901,
      "totalCounter": 1046,
      "invoiceCounterExtension": "КР",
      "totalAmount": 8990,
      "totalTax": 890.9009,
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1046\nБројач рачуна:                901/1046КР\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
    },
    "receipt": {
      "textUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/official-text",
      "jsonUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/canonical-json",
      "pdfA4Url": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/pdf-a4",
      "pdf80mmUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/pdf-80mm",
      "pdf58mmUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/pdf-58mm",
      "previewImageUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/preview-png",
      "qrImageUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/qr-svg",
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "preferredPaperFormat": "a4"
    },
    "reference": {
      "fiscalDocumentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "pfrNumber": "JWX4K9PL-JWX4K9PL-1045",
      "pfrTime": "2026-09-01T16:40:05.120+02:00"
    },
    "createdAt": "2026-09-01T08:15:31.902Z",
    "updatedAt": "2026-09-01T08:15:32.611Z"
  },
  "failureCode": null,
  "createdAt": "2026-09-01T14:40:04.300Z",
  "updatedAt": "2026-09-01T14:40:06.902Z"
}

When cash is returned BokaPOS immediately issues the refund copy too (`cashRefundCopy`) with the customer-signature line; print it and have the customer sign.

Partial refund

To return part of an order, send only the lines being returned, with the quantity being returned. If the original had two lines and the customer returns one of two pieces of the first, items holds one entry with originalLineIndex: 0 and quantity: 1. A later refund of the same line may return at most the remaining piece. Prices and labels do not change: what was on the receipt is what gets refunded.

Refunding other kinds

Advance: cancelling a wrong advance payment and closing the case are Аванс Рефундација, through /v1/advance-cases (Advance).
Proforma and Training: the refund must repeat the whole source document, through /v1/proforma-training-workflows (Proforma and Training).
A copy of an existing refund: POST /v1/fiscal-documents/{refund.id}/copies.

Refund errors

HTTP	Code	Meaning	What to do	Retry
422	`REFERENCE_DOCUMENT_NOT_FOUND`	The referenced document (`reference.fiscalDocumentId`) does not exist.	Check the identifier from the original receipt's response.	fix the request
422	`REFERENCE_DOCUMENT_NOT_FISCALIZED`	The referenced document is not fiscalized, so it cannot be a reference.	A reference may point only to a FISCALIZED document.	fix the request
422	`REFERENCE_DOCUMENT_SCOPE_MISMATCH`	The referenced document belongs to another taxpayer or premise.	A reference must stay on the same taxpayer and premise.	fix the request
422	`REFERENCE_DOCUMENT_TYPE_NOT_ALLOWED`	This invoice and transaction type may not reference that kind of source document (the official reference matrix).	See the reference table on the Conventions page.	fix the request
422	`REFUND_QUANTITY_EXCEEDS_ORIGINAL`	The returned quantity is larger than the quantity on the original line.	Lower the quantity; a partial refund is allowed.	fix the request
422	`REFUND_CUMULATIVE_QUANTITY_EXCEEDED`	The sum of every refund of that line so far would exceed the original quantity.	Check the earlier refunds in the journal.	never
422	`REFUND_ITEM_MUST_MATCH_ORIGINAL_LINE`	Name, price, labels or GTIN do not match the original line `originalLineIndex`.	Copy the item from the original receipt (`GET /v1/fiscal-documents/{id}/representations/canonical-json`).	fix the request
422	`REFUND_ORIGINAL_LINE_NOT_FOUND`	`originalLineIndex` does not exist on the original receipt.	Indexes start at zero, in the order of the original's items.	fix the request