Перейти к содержанию

Scenario 3. Refund payment

Pay API

Basic flow

This scenario explains your actions when you want to return (refund) payment to the customer. Note that this scenario can be triggered only after the payment transaction is completed.

Info

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.

Payment refund

Specific refund cases

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 (refundAmount) equal to total payment amount (totalAmount).

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 (refundAmount) to be less than total payment amount (totalAmount).

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 flows and possible errors

To start the refund scenario, send the POST /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.

  1. 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 requestId parameter. 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.

  2. If the first request is not received by the Koshelek host, and the second is received, it will be processed as the first one.

  3. If the checkout has received a response from the Koshelek host, the response body will contain the refTransactionId field. To obtain information on the status of this refund operation, invoke POST /status request with received refTransactionId value.

Warning

If the checkout has not received a response to the first POST /refund request and initiates a new request with 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 Pay API.

  • Green color indicates successful statuses.
  • Red indicates unsuccessful statuses.
  • Gray indicates transit statuses.

Cancel / Refund Transaction States