Accounts API4

Balance Transfers API3

Balances API5

Capabilities API1

Captures API3

Chargebacks API3

Checkout Sessions API2

Client Links API1

Clients API2

Customers API7

Delayed Routing API3

Draft Transfers API4

Invoices API2

Mandates API4

Methods API7

OAuth API2

Onboarding API2

Organizations API3

Payment Links API6

Payments API6

Payouts API4

Permissions API2

Profiles API6

Refunds API5

Sales Invoices API5

Settlements API8

Subscriptions API7

Terminals API6

Transfers API2

Unmatched Credit Transfers API4

Verify Payee API1

Wallets API1

Webhook Events API1

Webhooks API6

Payments API

Update payment

Certain details of an existing payment can be updated.

Updating the payment details will not result in a webhook call.

patch/v2/payments/{paymentId}

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

descriptionstring

The description of the payment will be shown to your customer on their card or bank statement when possible. We truncate the description automatically according to the limits of the used payment method. The description is also visible in any exports you generate.

We recommend you use a unique identifier so that you can always link the payment to the order in your back office. This is particularly useful for bookkeeping.

The maximum length of the description field differs per payment method, with the absolute maximum being 255 characters. The API will not reject strings longer than the maximum length but it will truncate them to fit.

redirectUrlstring nullable

The URL your customer will be redirected to after the payment process.

It could make sense for the redirectUrl to contain a unique identifier – like your order ID – so you can show the right page referencing the order when your customer returns.

The parameter is normally required, but can be omitted for recurring payments (sequenceType: recurring) and for Apple Pay payments with an applePayPaymentToken.

cancelUrlstring nullable

The URL your customer will be redirected to when the customer explicitly cancels the payment. If this URL is not provided, the customer will be redirected to the redirectUrl instead — see above.

Mollie will always give you status updates via webhooks, including for the canceled status. This parameter is therefore entirely optional, but can be useful when implementing a dedicated customer-facing flow to handle payment cancellations.

webhookUrlstring nullable

The webhook URL where we will send payment status updates to.

The webhookUrl is optional, but without a webhook you will miss out on important status changes to your payment.

The webhookUrl must be reachable from Mollie's point of view, so you cannot use localhost. If you want to use webhook during development on localhost, you must use a tool like ngrok to have the webhooks delivered to your local machine.

Sets the language for customer-facing content and communications.

dueDatestring nullable

The date by which the payment should be completed in YYYY-MM-DD format. Sending null has the same effect as omitting the field.

restrictPaymentMethodsToCountrystring nullable

For digital goods in most jurisdictions, you must apply the VAT rate from your customer's country. Choose the VAT rates you have used for the order to ensure your customer's country matches the VAT country.

Use this parameter to restrict the payment methods available to your customer to those from a single country.

If available, the credit card method will still be offered, but only cards from the allowed country are accepted.

The field expects a country code in ISO 3166-1 alpha-2 format, for example NL.

testmodeboolean

Whether the entity was created in test mode or live mode. This field does not update the mode of the entity.

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.

issuerstring nullable

Only relevant for iDEAL, KBC/CBC, gift card, and voucher payments.

⚠️ With the introduction of iDEAL 2 in 2025, this field will be ignored for iDEAL payments. For more information on the migration, refer to our help center.

Some payment methods are a network of connected banks or card issuers. In these cases, after selecting the payment method, the customer may still need to select the appropriate issuer before the payment can proceed.

We provide hosted issuer selection screens, but these screens can be skipped by providing the issuer via the API up front.

The full list of issuers for a specific method can be retrieved via the Methods API by using the optional issuers include.

A valid issuer for iDEAL is for example ideal_INGBNL2A (for ING Bank).

billingEmailstring

Example request

{
  "description": "Chess Board",
  "redirectUrl": "https://example.org/redirect",
  "cancelUrl": "https://example.org/cancel",
  "webhookUrl": "https://example.org/webhooks",
  "method": "ideal",
  "locale": "en_US",
  "dueDate": "2025-01-01",
  "restrictPaymentMethodsToCountry": "NL",
  "issuer": "ideal_INGBNL2A",
  "billingAddress": {
    "title": "Mr.",
    "givenName": "Piet",
    "familyName": "Mondriaan",
    "organizationName": "Mollie B.V.",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "Apt. 1",
    "postalCode": "1234AB",
    "email": "piet@example.org",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL"
  },
  "shippingAddress": {
    "title": "Mr.",
    "givenName": "Piet",
    "familyName": "Mondriaan",
    "organizationName": "Mollie B.V.",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "Apt. 1",
    "postalCode": "1234AB",
    "email": "piet@example.org",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL"
  },
  "billingEmail": "test@example.com"
}

Response

The updated payment object.

Changes

Changed in 14 of the 78 revisions of this API.664152

Aug 27, 20268e5a936eb5bd6See the full diff
- ●
  added the new Cartes Bancaires enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new cartes-bancaires-business enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new cartes-bancaires-consumer enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new mastercard-debit-consumer-inter enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-debit-consumer-inter enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-debit-consumer-intra-eea enum value to the ///// response property for the response status
  response-property-enum-value-added
Aug 7, 202686a9cd830b063See the full diff
- ●
  added the new en_BE enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new en_NL enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-credit-consumer-inter enum value to the ///// response property for the response status
  response-property-enum-value-added
Aug 6, 202664c0511a62bc28131See the full diff
- ▲
  removed the enum value ca_ES of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value cs_CZ of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value da_DK of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value de_AT of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value de_CH of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value de_DE of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value de_LU of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value en_GB of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value en_US of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value es_ES of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value fi_FI of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value fr_BE of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value fr_FR of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value fr_LU of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value hu_HU of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value is_IS of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value it_IT of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value lt_LT of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value lv_LV of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value nb_NO of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value nl_BE of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value nl_NL of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value null of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value pl_PL of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value pt_PT of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value sk_SK of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value sv_SE of the request property
  request-property-enum-value-removed
- ▲
  the request property type changed from object to no type
  request-property-type-changed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  added the new undefined enum value to the //// response property for the response status
  response-property-enum-value-added
- ○
  removed the null enum value from the //// response property for the response status
  response-property-enum-value-removed
Aug 5, 202642479670d8c911See the full diff
- ▲
  the response property //// became nullable for the status
  response-property-became-nullable
- ○
  the request property became nullable
  request-property-became-nullable
Jul 30, 2026160fcdd65af712See the full diff
- ●
  added the new billink enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  added the new billink enum value to the request property ////
  request-property-enum-value-added
- ○
  added the new billink enum value to the request property //
  request-property-enum-value-added
Jul 8, 20264d4ab81fb2d522See the full diff
- ●
  added the new cs_CZ enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new sk_SK enum value to the //// response property for the response status
  response-property-enum-value-added
- ○
  added the new cs_CZ enum value to the request property
  request-property-enum-value-added
- ○
  added the new sk_SK enum value to the request property
  request-property-enum-value-added
Jul 2, 2026226f9009e92813See the full diff
- ●
  added the new mastercard-credit-business-domestic enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new mastercard-credit-consumer-domestic enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new mastercard-credit-consumer-intra-eea enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new mastercard-debit-business-domestic enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new mastercard-debit-business-intra-eea enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new mastercard-debit-consumer-domestic enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new mastercard-debit-consumer-intra-eea enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-credit-business-domestic enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-credit-consumer-domestic enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-credit-consumer-intra-eea enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-debit-business-domestic enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-debit-business-intra-eea enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new visa-debit-consumer-domestic enum value to the ///// response property for the response status
  response-property-enum-value-added
Jun 22, 2026245eb8c595343739See the full diff
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  removed the enum value alma of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value applepay of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value bacs of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value bancomatpay of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value bancontact of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value banktransfer of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value belfius of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value billie of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value bizum of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value blik of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value creditcard of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value directdebit of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value eps of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value giftcard of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value ideal of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value in3 of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value kbc of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value klarna of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value mbway of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value mobilepay of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value multibanco of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value mybank of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value paybybank of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value paypal of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value paysafecard of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value pointofsale of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value przelewy24 of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value riverty of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value satispay of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value swish of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value trustly of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value twint of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value vipps of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value voucher of the request property
  request-property-enum-value-removed
- ▲
  the request property type changed from string null to no type
  request-property-type-changed
- ▲
  the //// response's property type changed from string null to no type for status
  response-property-type-changed
- ○
  added subschema #2 to the request property oneOf list
  request-property-one-of-added
- ○
  removed the alma enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the applepay enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the bacs enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the bancomatpay enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the bancontact enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the banktransfer enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the belfius enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the billie enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the bizum enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the blik enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the creditcard enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the directdebit enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the eps enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the giftcard enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ideal enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the in3 enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the kbc enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the klarna enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the klarnapaylater enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the klarnapaynow enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the klarnasliceit enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the mbway enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the mobilepay enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the multibanco enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the mybank enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the paybybank enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the payconiq enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the paypal enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the paysafecard enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the pointofsale enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the przelewy24 enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the riverty enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the satispay enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the swish enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the trustly enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the twint enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the vipps enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the voucher enum value from the //// response property for the response status
  response-property-enum-value-removed
Jun 9, 2026327472893a891See the full diff
- ●
  added the new googlepay enum value to the ///// response property for the response status
  response-property-enum-value-added
May 19, 20267cab62b218301See the full diff
- ○
  added the non-success response with the status
  response-non-success-status-added

Of the 78 revisions, 9 have no diff computed.

Full history (14 revisions)