For up-to-date documentation, see the latest version.
Refunds
Payment may be refunded multiple times for a total amount not exceeding the payment amount and it is allowed only for
payments in status CONFIRMED.
Paynow accepts refunds with a minimum amount 1 PLN for CARD payment, for other 0.01 PLN.
To be able to make refund by API your shop must have enabled "Once a day" variant of payout schedule for given shop. The funds needed to make the return will be taken from your balance.
Awaiting refunds - optional
Awaiting refund is a special type of refund which can be initialized even if the refund amount exceeds your balance.
After initialization, such refund will be in NEW status.
When enough funds have been accumulated on your balance, refunds will be processed using FIFO algorithm (that means the
refunds are being processed in the order in which they were initialized).
If you do not accumulate the necessary funds for a refund on your balance for 120 hours (5 days, default value), the
refund status will change to CANCELLED.
You can change the time after which awaiting refunds will be cancelled - the unit of this parameter is an hour.
To enable this feature for your shop and/or change the default awaiting refund cancellation time (optional) go
to Settings > Awaiting refunds tab in the Merchant Panel.
Flow diagram
The following picture shows the positive refund flow:
Flow of statuses
The following picture shows all the statuses that a refund can take, and possible transitions between those statuses:
Explanation:
| Code | Description |
|---|---|
| NEW | Refund has been accepted. |
| PENDING | Paynow starts to process the request. |
| SUCCESSFUL | Refund has been successfully processed by Paynow and money has been transferred to the buyers account. |
| FAILED | Refund encountered a problem during the processing. Money has not been transferred to the Buyer. |
| CANCELLED | Refund was cancelled. Money has not been transferred to the Buyer. Only refunds in status NEW can be cancelled. |
Make a refund
For the purpose of this guide, let's assume that your keys are:
- Api-Key =
97a55694-5478-43b5-b406-fb49ebfdd2b5 - Signature-Key =
b305b996-bca5-4404-a0b7-2ccea3d2b64b
Let's also assume, that paymentId is NOR3-FUN-D4U-LOL
Step 1: Prepare a refund request message. Throughout this example, we'll use a simple message containing only required fields which look as follows:
{
"amount": 997,
"reason": "RMA"
}
The provided amount should be given in the smallest unit of refund currency (grosz in case of PLN). This means that the above request defines a refund for 9.97 PLN. Description field should contain reason of refund. Full specification for refund request message can be found below.
Step 2: Attach Api-Key header with the value of Api-Key available in the Merchant Panel.
Step 3: Calculate signature and attach it as the Signature header. For given
example correct signature is IExnDYF3U/A6y0UKm6VnuOMz0+uXsxMcZRg8h4QgZAE=
If you are trying to calculate the signature from the example in your code and are getting a different result, make sure that your JSON message is formatted the same way as the message in the example, i.e. with four-space indentation and no newline character at the end.
Step 4: Generate random string with maximum length of 45 characters for an Idempotency-Key header.
Step 5: Make a POST with prepared message on refund request endpoint
curl --request POST 'https://api.sandbox.paynow.pl/v1/payments/NOR3-FUN-D4U-LOL/refunds' \
-H 'Content-Type: application/json' \
-H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
-H 'Signature: IExnDYF3U/A6y0UKm6VnuOMz0+uXsxMcZRg8h4QgZAE=' \
-H 'Idempotency-Key: 59c6dd26-f905-487b-96c9-fd1d2bd76885' \
--data-raw '{
"amount": 997,
"reason": "RMA"
}'
Bear in mind, that the request must include Host and Accept headers as
described here. They are not listed above explicitly as the curl
command includes them by default.
Step 6: Handle the returned response:
{
"refundId": "R3FU-UND-D8K-WZD",
"status": "PENDING"
}
The response contains ID of the refund generated by Paynow and the current status of the refund.
Returned refundId should be saved by Merchant for further reference.
Step 7: Query the status of refund. See get refund status endpoint description.
curl --location --request GET 'https://api.sandbox.paynow.pl/v1/refunds/R3FU-UND-D8K-WZD/status' \
--header 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5'
To see more details about statuses, please refer to the Flow Diagram
Cancel awaiting refund
If you have enabled awaiting refunds mechanism
every new balance refund will be executed with some delay. When refund is in status NEW (awaiting) you can cancel it
using an API request.
Below you can see how to do it.
For this guide purposes let's assume that:
- Your Api-Key is:
97a55694-5478-43b5-b406-fb49ebfdd2b5 - Your Refund Id is:
RE1-K7E-206-31J
Step 1: Generate random string with maximum length of 45 characters for an Idempotency-Key header.
Step 2: Make this call to our API:
curl --location --request POST 'https://api.sandbox.paynow.pl/v1/refunds/RE1-K7E-206-31J/cancel' \
-H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
-H 'Idempotency-Key: a796913a-4a56-4be3-8145-abb1c9da377d' \
Please, keep in mind that with this call you can only cancel refunds from balance that are in NEW status.