Create payment refund

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

Creates a refund for a specific payment. The refunded amount is credited to your customer usually either via a bank transfer or by refunding the amount to your customer’s credit card.

Parameters

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

amountamount objectrequired

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

Show child parameters

currencystringrequired
An ISO 4217 currency code. The currency must be the same as the corresponding payment.
valuestringrequired
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.
descriptionstringoptional
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.
metadatamixedoptional
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 will 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, you can enable test mode through the testmode parameter.

testmodebooleanoptional

Mollie Connect parameters

With Mollie Connect you can split payments that are processed through your app across multiple connected accounts. When creating refunds for those split payments, you can use the reverseRouting parameter to pull the split payment back to the platform balance. To learn more about creating refunds for split payments, please refer to the Splitting payments guide.

reverseRoutingbooleanoptional

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
 5
 6
 7
 8
 9
10
11
12
const { createMollieClient } = require('@mollie/api-client');
const mollieClient = createMollieClient({ apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

(async () => {
  const refund = await mollieClient.payments_refunds.create({
    paymentId: 'tr_WDqYK6vllg',
    amount: {
      value: '5.95',
      currency: 'EUR',
    },
  });
})();

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-payment-refund",
            "type": "text/html"
        }
    }
}

Response (duplicate refund detected)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
HTTP/1.1 409 Conflict
Content-Type: application/hal+json

 {
     "status": 409,
     "title": "Conflict",
     "detail": "A duplicate refund has been detected",
     "_links": {
         "documentation": {
             "href": "https://docs.mollie.com/overview/handling-errors",
             "type": "text/html"
         }
     }
 }