Sign in
Refunds API

Create payment refund

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.

post/v2/payments/{paymentId}/refunds

Headers

idempotency-keystring
Example:123e4567-e89b-12d3-a456-426

A unique key to ensure idempotent requests. This key should be a UUID v4 string.

Request body

resourcestring

Indicates the response contains a refund object. Will always contain the string refund for this endpoint.

idstring
mode'live' | 'test'

Whether this entity was created in live mode or in test mode.

descriptionstring nullable

The description of the refund that may be shown to your customer, depending on the payment method used.

paymentIdstring
settlementIdstring
status'queued' | 'pending' | 'processing' | 'refunded' | 'failed' | 'canceled'
createdAtstring

The entity's date and time of creation, in ISO 8601 format.

reverseRoutingboolean nullable

This feature is only available to marketplace operators.

With Mollie Connect you can charge fees on payments that your app is processing on behalf of other Mollie merchants, by providing the routing object during payment creation.

When creating refunds for these routed payments, by default the full amount is deducted from your balance.

If you want to pull back the funds that were routed to the connected merchant(s), you can set this parameter to true when issuing a full refund.

For more fine-grained control and for partial refunds, use the routingReversals parameter instead.

testmodeboolean nullable

Whether to create the entity in test mode or live mode.

Most API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting testmode to true.

Example request

{
  "resource": "refund",
  "id": "re_5B8cwPMGnU",
  "mode": "live",
  "description": "Refunding a Chess Board",
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "paymentId": "tr_5B8cwPMGnU",
  "settlementId": "stl_5B8cwPMGnU",
  "status": "queued",
  "createdAt": "2024-03-20T09:13:37+00:00",
  "externalReference": {
    "type": "acquirer-reference"
  },
  "routingReversals": [
    {
      "amount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "source": {
        "type": "organization",
        "organizationId": "org_1234567"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "payment": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "settlement": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "documentation": {
      "href": "https://...",
      "type": "application/hal+json"
    }
  }
}

Response

The newly created refund object.

Changes

Changed in 6 of the 92 revisions of this API.11313

  • 26176035db5811See the full diff
    • ▲

      the response property //// became nullable for the status

      response-property-became-nullable

    • ○

      the request property //// became nullable

      request-property-became-nullable

  • eca80d9f39721036See the full diff
    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ●

      removed the optional property from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property from the response with the status

      response-optional-property-removed

    • ○

      the request property //// became optional

      request-property-became-optional

    • ○

      the request property //// became optional

      request-property-became-optional

    • ○

      the request property //// became optional

      request-property-became-optional

    • ○

      added to the response body allOf list for the response status

      response-body-all-of-added

    • ○

      removed the optional write-only property reverseRouting from the response with the status

      response-optional-write-only-property-removed

    • ○

      removed the optional write-only property testmode from the response with the status

      response-optional-write-only-property-removed

  • 5e44242e94d31See the full diff
    • ○

      the response property became required for the status

      response-property-became-required

  • 7cab62b218301See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • ef4b5a97b56a2See the full diff
    • ○

      the endpoint scheme security advancedAccessToken was added to the API

      api-security-added

    • ○

      the endpoint scheme security organizationAccessToken was removed from the API

      api-security-removed

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 18e0e58eb54d2See the full diff
    • ○

      request property //// deprecated

      request-property-deprecated

    • ○

      response property settlementAmount deprecated

      response-property-deprecated

Of the 92 revisions, 9 have no diff computed.