Scenario 3. Refund payment
Koshelek Pay API
Documentation has moved
The information on this page is no longer updated and may be obsolete. The most current Koshelek documentation is now available at the new address:
Refund payment: basic flow
This scenario describes your actions when you want to return (refund) payment to a customer. Note that this scenario can be triggered only after the payment transaction is completed.
Refunds do not imply any actions to be taken with the Koshelek App — i.e. you don't have to scan loyalty card to make a refund.
Specific refund cases
1. Full refund
To make full refund, it is expected that you specify:
goods (
items) that were specified earlier in payment request;number of items (
quantity) equal to that specified in payment request;refund amount (
refAmount) equal to total payment amount (totalAmount).
2. Partial refund
To make partial refund, it is expected that you specify:
only goods (
items) being returned;exact number of items (
quantity) being returned;refund amount (
refAmount) to be less than total payment amount (totalAmount).
3. Refund for non-piece items
For non-piece items (i.e. those with measure value different from PIECE — e.g. items sold by weight), only full refund is available for non-piece slip positions.
Alternative refund scenarios and possible errors
To start the refund scenario, send the /refund request to the Koshelek host. If the request is received by the Koshelek host, the refund operation will be started. The started refund operation cannot be canceled.
If the checkout for some reason has not received a response from the Koshelek host to this request, then the request can be sent again with the same value of the
requestIdparameter. This is mandatory since if the first request reached the Koshelek host, but the response to it was lost, then the Koshelek host will consider the new request as a repeated call of the first request — the checkout will receive a response to the first request. The idempotency rule applies.If the first request is not received by the Koshelek host, and the second is received, it will be processed as the first one.
If the checkout has received a response from the Koshelek host, the response body will contain the
refTransactionIdfield. To obtain information on the status of this refund operation, use the/statusrequest with the receivedrefTransactionIdvalue.
If the checkout has not received a response to the first /refund request and initiates a new request with a changed requestId value, the Koshelek host will process it as a new refund request, and in this case, a double refund to the user's account is possible.
Cancel / refund transaction states
The diagram shows transaction status transitions during payment cancellation and refund operations initiated via Koshelek Pay API.
Green color indicates successful statuses.
Red indicates unsuccessful statuses.
Yellow indicates transit statuses.
Last updated
