Skip to content
/
Refunds
Last updated

Refunds

The SimPay system allows for easy and automated refunding of funds to customers (e.g., in case of withdrawal from a contract, complaint, or order cancellation). You can initiate this process directly from our API, without the need to manually order bank transfers from the Billing Panel.

Formal and Technical Requirements

Before initiating a refund, make sure the given transaction meets all of the following conditions. If any of them are not met, the API will return an error.

  • Transaction status: The transaction must be fully paid (have the transaction_paid status).
  • Available balance: Your account (SimPay balance) must have sufficient funds to cover the refund being ordered.
  • Maximum amount: The sum of all previous refunds for a given transaction cannot exceed its original value.
  • Transaction age: A refund can only be ordered for transactions that are no older than 30 days.
  • No tests: Refunds can only be made for real (production) transactions. You cannot order a refund for a test transaction.
  • No duplicates: At any given time, a transaction cannot have another pending refund order (status refund_new or refund_pending). You must wait for the previous order to finish processing.

Full and Partial Refunds

Depending on your needs, SimPay allows two types of refunds:

  1. Partial refund – you return only part of the amount to the customer (e.g., when they return only one of several ordered products). To perform it, pass the amount parameter with the appropriate amount in the request body.
  2. Full refund (100%) – you return the entire paid amount. You have two options here: you can omit the amount parameter in the request (the system will then refund the full transaction value by default) or explicitly provide the original order amount.

Creating a Refund (API Examples)

To generate a refund, send a POST request to the endpoint: /payment/{serviceId}/transactions/{transactionId}/refunds

Example: Partial Refund (e.g., for 25.50 PLN)

curl -X POST "https://api.simpay.pl/payment/{serviceId}/transactions/{transactionId}/refunds" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": "25.50"
  }'

Example: Full Refund (omitting the amount parameter)

curl -X POST "https://api.simpay.pl/payment/{serviceId}/transactions/{transactionId}/refunds" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{}'

API Response and refundId Identifier

After sending a valid request, the operation will be queued and will receive an initial status of refund_new. In the response from our API, you will receive an object containing a unique identifier for this order – refundId.

Important: Remember to save the refundId value in your database alongside the transaction identifier! It will be essential for correctly matching and handling future IPN notifications (webhooks) with status changes for this specific refund.

Refund Lifecycle

Ordering a refund does not mean that the money will immediately appear in the customer's account. This process is subject to specific stages and system statuses.

👉 Go to: Refund Statuses, to check the full lifecycle, transition diagrams, and instructions on how we notify your application about the successful completion of a refund operation.

Previous page
Next page