Create payment refund

Refunds API v2
POSThttps://api.mollie.com/v2/payments/*id*/refunds
Authentication:API keysOrganization access tokensApp access tokens

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 full refunds for those split payments, you can use the reverseRouting parameter to pull the split payment back to the platform balance.

reverseRoutingbooleanoptional

When creating partial refunds for split payments, you should instead use the routingReversals array to set the amount that you want to pull back from the single routes.

routingReversalsarrayoptional

To learn more about creating refunds for split payments, refer to the Refunds and chargebacks for split payments guide.

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 = payment.refunds.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
const { createMollieClient } = require('@mollie/api-client');
const mollieClient = createMollieClient({ apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

const refund = await mollieClient.paymentRefunds.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"
         }
     }
 }