Create payment refund

Refunds API v2
POSThttps://api.mollie.com/v2/payments/*id*/refunds

Most payment methods support refunds. This means you can request your payment to be refunded to your customer. The refunded amount will be withheld from your next settlement.

Refunds are not available at all for paysafecard and gift cards.

Refunds support descriptions, which we will show in the Dashboard, your exports and pass to your customer if possible.

If you have insufficient balance with Mollie to perform the refund, the refund will be queued. We will automatically process the refund once your balance increases.

Any payments created for Orders can also be refunded using the Payment Refunds API. However, we recommend using the Order Refund API in those cases so you can pass the order lines you are refunding too. For pay after delivery methods, this will improve your customer’s experience.

Possible errors

Sometimes a situation can occur in which it is not possible to perform the refund. In such cases an HTTP 4xx error will be returned. Some of these situations are illustrated here:

  • There might not be enough balance on your account with the payment provider (e.g. PayPal).
  • You may have forgotten to grant the appropriate rights to Mollie for the payment provider (PayPal only).
  • It is possible that the payment has already been (partially) refunded.
  • It is not always possible to do a partial refund.

If you perform many refunds in parallel, you may get an HTTP 503 Service unavailable error. In this case, you can be certain the refund was not performed and you can safely retry the refund.

If there is a connection issue during the creation of a refund (e.g. a client-side time out is triggered) you should not retry automatically as you cannot be sure the refund has been performed or not. In this case we suggest logging into the Mollie Dashboard, or retrieving the payment’s refunds via the API to validate if the refund has been created.

Parameters

Replace id in the endpoint URL by the payment’s ID, for example v2/payments/tr_7UhSN1zuXS/refunds.

amount

amount object
required

The amount to refund. For some payments, it can be up to €25.00 more than the original transaction amount.

currency

string
required
An ISO 4217 currency code. The currency must be the same as the corresponding payment.

value

string
required
A string containing the exact amount you want to refund in the given currency. Make sure to send the right amount of decimals. Non-string values are not accepted.

description

string
optional
The description of the refund you are creating. This will be shown to the consumer on their card or bank statement when possible. Max. 140 characters.

metadata

mixed
optional
Provide any data you like, for example a string or a JSON object. We will save the data alongside the refund. Whenever you fetch the refund with our API, we’ll also include the metadata. You can use up to approximately 1kB.

Access token parameters

If you are using organization access tokens or are creating an OAuth app, the testmode parameter is also available.

testmode

boolean
optional
Set this to true to refund a test mode payment.

Response

201 application/hal+json

A refund object is returned, as described in Get payment refund.

Example

cURLPHPPythonRubyNode.js
1
2
3
4
5
curl -X POST https://api.mollie.com/v2/payments/tr_WDqYK6vllg/refunds \
   -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
   -d "amount[currency]=EUR" \
   -d "amount[value]=5.95" \
   -d "metadata={\"bookkeeping_id\": 12345}"
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");

$payment = $mollie->payments->get("tr_WDqYK6vllg");
$refund = $payment->refund([
"amount" => [
   "currency" => "EUR",
   "value" => "5.95" // You must send the correct number of decimals, thus we enforce the use of strings
]
]);
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from mollie.api.client import Client

mollie_client = Client()
mollie_client.set_api_key('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM')

payment = mollie_client.payments.get('tr_WDqYK6vllg')
refund = mollie_client.payment_refunds.on(payment).create({
   'amount': {
         'value': '5.95',
         'currency': 'EUR'
   }
})
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
require 'mollie-api-ruby'

Mollie::Client.configure do |config|
  config.api_key = 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM'
end

refund = Mollie::Payment::Refund.create(
  payment_id: 'tr_WDqYK6vllg',
  amount:      { value: '5.00', currency: 'EUR' }
  description: 'Example refund description'
)
1
2
3
4
We don't have a Node.js code example for this API call yet.

If you have some time to spare, feel free to open a pull request at:
https://github.com/mollie/api-documentation

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
HTTP/1.1 201 Created
Content-Type: application/hal+json

{
    "resource": "refund",
    "id": "re_4qqhO89gsT",
    "amount": {
        "currency": "EUR",
        "value": "5.95"
    },
    "status": "pending",
    "createdAt": "2018-03-14T17:09:02.0Z",
    "description": "Order #33",
    "metadata": {
         "bookkeeping_id": 12345
    },
    "paymentId": "tr_WDqYK6vllg",
    "_links": {
        "self": {
            "href": "https://api.mollie.com/v2/payments/tr_WDqYK6vllg/refunds/re_4qqhO89gsT",
            "type": "application/hal+json"
        },
        "payment": {
            "href": "https://api.mollie.com/v2/payments/tr_WDqYK6vllg",
            "type": "application/hal+json"
        },
        "documentation": {
            "href": "https://docs.mollie.com/reference/v2/refunds-api/create-refund",
            "type": "text/html"
        }
    }
}