MOmollie
Orders API

Create order payment

⚠️ We no longer recommend using the Orders API. Please refer to the Payments API instead.

An order has an automatically created payment that your customer can use to pay for the order. When the payment expires you can create a new payment for the order using this endpoint. A maximum of 25 payments can be created for an order.

A new payment can only be created while the status of the order is created, and when the status of the existing payment is either expired, canceled or failed.

The endpoint accepts virtually all parameters accepted by the regular Create payment endpoint. Please refer to that endpoint for the full documentation of all parameters.

The payment inherits certain properties, such as the amount and webhookUrl, directly from the order. These cannot be changed via this endpoint.

🔑 Access with

API key

Advanced access token with payments.write

OAuth access with payments.write

post/orders/{orderId}/payments

Request

  • Base URL
    https://api.mollie.com/v2
  • URL
    https://api.mollie.com/v2/orders/{orderId}/payments
  • Auth
    • HTTP bearer
    • or HTTP bearer
    • or OAuth 2
      Authorization code: https://my.mollie.com/oauth2/authorize
      Token URL: https://api.mollie.com/oauth2/tokens scopes: payments.write

Request body

customerIdstring nullable

The ID of the customer the payment is being created for. This is used primarily for recurring payments, but can also be used on regular payments to enable single-click payments.

If sequenceType is set to recurring, this field is required.

mandateIdstring nullable

Only relevant for recurring payments and stored cards.

When creating recurring or stored cards payments, the ID of a specific mandate can be supplied to indicate which of the customer's accounts should be debited.

sequenceTypestring

Only relevant for recurring payments.

Indicate which part of a recurring sequence this payment is for.

Recurring payments can only take place if a mandate is available. A common way to establish such a mandate is through a first payment. With a first payment, the customer agrees to automatic recurring charges taking place on their account in the future.

If set to recurring, the customer's card is charged automatically.

Defaults to oneoff, which is a regular non-recurring payment.

For PayPal payments, recurring is only possible if your connected PayPal account allows it. You can call our Methods API with parameter sequenceType: first to discover which payment methods on your account are set up correctly for recurring payments.

Possible values: oneoff first recurring

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.

Example request

{
  "method": "ideal",
  "customerId": "cst_5B8cwPMGnU",
  "mandateId": "mdt_5B8cwPMGnU",
  "sequenceType": "oneoff",
  "webhookUrl": "https://example.org/webhooks",
  "applicationFee": {
    "amount": {
      "currency": "EUR",
      "value": "10.00"
    },
    "description": "Platform fee"
  }
}

Response

The newly created payment object.

resourcestring required

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

idstring required

The identifier uniquely referring to this payment. Mollie assigns this identifier at payment creation time. Mollie will always refer to the payment by this ID. Example: tr_5B8cwPMGnU6qLbRvo7qEZo.

modestring required

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

Possible values: live test

descriptionstring required

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.

localestring nullable

Allows you to preset the language to be used in the hosted payment pages shown to the customer. Setting a locale is highly recommended and will greatly improve your conversion rate. When this parameter is omitted the browser language will be used instead if supported by the payment method. You can provide any xx_XX format ISO 15897 locale, but our hosted payment pages currently only support the specified languages.

For bank transfer payments specifically, the locale will determine the target bank account the customer has to transfer the money to. We have dedicated bank accounts for Belgium, Germany, and The Netherlands. Having the customer use a local bank account greatly increases the conversion and speed of payment.

Possible values: ca_ES cs_CZ da_DK de_AT de_CH de_DE de_LU el_GR en_BE en_GB en_NL en_US es_ES fi_FI fr_BE fr_FR fr_LU hu_HU is_IS it_IT lt_LT lv_LV nb_NO nl_BE nl_NL pl_PL pt_PT sk_SK sl_SI sv_SE tr_TR

countryCodestring nullable

This optional field contains your customer's ISO 3166-1 alpha-2 country code, detected by us during checkout. This field is omitted if the country code was not detected.

methodstring nullable

The payment method used for this transaction. If a specific method was selected during payment initialization, this field reflects that choice.

Possible values: alma applepay bacs bancomatpay bancontact banktransfer belfius billie billink bizum blik creditcard directdebit eps giftcard ideal in3 kbc klarna mbway mobilepay multibanco mybank paybybank paypal paysafecard pointofsale przelewy24 riverty satispay swish trustly twint vipps voucher wero

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).

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.

captureModestring nullable

Indicate if the funds should be captured immediately or if you want to place a hold and capture at a later time.

This field needs to be set to manual for method riverty.

Possible values: automatic manual

captureDelaystring nullable

Only relevant if you wish to manage authorization and capturing separately.

Some payment methods allow placing a hold on the card or bank account. This hold or 'authorization' can then at a later point either be 'captured' or canceled.

By default, we charge the customer's card or bank account immediately when they complete the payment. If you set a capture delay however, we will delay the automatic capturing of the payment for the specified amount of time. For example 8 hours or 2 days.

To schedule an automatic capture, the captureMode must be set to automatic.

The maximum delay is 7 days (168 hours).

Possible values: ... hours ... days

captureBeforestring nullable

Indicates the date before which the payment needs to be captured, in ISO 8601 format. From this date onwards we can no longer guarantee a successful capture. The parameter is omitted if the payment is not authorized (yet).

sequenceTypestring required

Only relevant for recurring payments.

Indicate which part of a recurring sequence this payment is for.

Recurring payments can only take place if a mandate is available. A common way to establish such a mandate is through a first payment. With a first payment, the customer agrees to automatic recurring charges taking place on their account in the future.

If set to recurring, the customer's card is charged automatically.

Defaults to oneoff, which is a regular non-recurring payment.

For PayPal payments, recurring is only possible if your connected PayPal account allows it. You can call our Methods API with parameter sequenceType: first to discover which payment methods on your account are set up correctly for recurring payments.

Possible values: oneoff first recurring

subscriptionIdstring nullable

If the payment was automatically created via a subscription, the ID of the subscription will be added to the response.

mandateIdstring nullable

Only relevant for recurring payments and stored cards.

When creating recurring or stored cards payments, the ID of a specific mandate can be supplied to indicate which of the customer's accounts should be debited.

customerIdstring nullable

The ID of the customer the payment is being created for. This is used primarily for recurring payments, but can also be used on regular payments to enable single-click payments.

If sequenceType is set to recurring, this field is required.

profileIdstring required

The identifier referring to the profile this entity belongs to.

When using an API Key, the profileId must not be sent since it is linked to the key. However, for OAuth and Organization tokens, the profileId is required.

For more information, see Authentication.

settlementIdstring nullable

The identifier referring to the settlement this payment was settled with.

orderIdstring nullable

If the payment was created for an order, the ID of that order will be part of the response.

statusstring required

The payment's status. Refer to the documentation regarding statuses for more info about which statuses occur at what point.

Possible values: open pending authorized paid canceled expired failed

isCancelableboolean nullable

Whether the payment can be canceled. This parameter is omitted if the payment reaches a final state.

createdAtstring required

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

authorizedAtstring nullable

The date and time the payment became authorized, in ISO 8601 format. This parameter is omitted if the payment is not authorized (yet).

paidAtstring nullable

The date and time the payment became paid, in ISO 8601 format. This parameter is omitted if the payment is not completed (yet).

canceledAtstring nullable

The date and time the payment was canceled, in ISO 8601 format. This parameter is omitted if the payment is not canceled (yet).

expiresAtstring nullable

The date and time the payment will expire, in ISO 8601 format. This parameter is omitted if the payment can no longer expire.

expiredAtstring nullable

The date and time the payment was expired, in ISO 8601 format. This parameter is omitted if the payment did not expire (yet).

failedAtstring nullable

The date and time the payment failed, in ISO 8601 format. This parameter is omitted if the payment did not fail (yet).

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.

storeCredentialsboolean

Whether the card details should be stored for the customer after a successful payment. This will create a mandate for the customer, allowing for future customer present saved-card CIT payments. Requires customerId, cardToken, and the creditcard method to be specified.

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 response

{
  "resource": "payment",
  "id": "tr_5B8cwPMGnU",
  "mode": "live",
  "description": "Chess Board",
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountRefunded": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountRemaining": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountCaptured": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountChargedBack": {
    "currency": "EUR",
    "value": "10.00"
  },
  "settlementAmount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "redirectUrl": "https://example.org/redirect",
  "cancelUrl": "https://example.org/cancel",
  "webhookUrl": "https://example.org/webhooks",
  "lines": [
    {
      "type": "physical",
      "description": "LEGO 4440 Forest Police Station",
      "quantity": 1,
      "quantityUnit": "pcs",
      "unitPrice": {
        "currency": "EUR",
        "value": "10.00"
      },
      "discountAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "totalAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "vatRate": "21.00",
      "vatAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "sku": "9780241661628",
      "categories": [
        "meal",
        "eco"
      ],
      "imageUrl": "https://...",
      "productUrl": "https://...",
      "recurring": {
        "description": "Gym subscription",
        "interval": "12 months",
        "amount": {
          "currency": "EUR",
          "value": "10.00"
        },
        "times": 1,
        "startDate": "2024-12-12"
      }
    }
  ],
  "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"
  },
  "locale": "en_US",
  "countryCode": "BE",
  "method": "ideal",
  "issuer": "ideal_INGBNL2A",
  "restrictPaymentMethodsToCountry": "NL",
  "captureMode": "manual",
  "captureDelay": "8 hours",
  "captureBefore": "2024-03-20T09:28:37+00:00",
  "applicationFee": {
    "amount": {
      "currency": "EUR",
      "value": "10.00"
    },
    "description": "Platform fee"
  },
  "routing": [
    {
      "resource": "route",
      "id": "rt_5B8cwPMGnU",
      "mode": "live",
      "amount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "destination": {
        "type": "organization",
        "organizationId": "org_1234567"
      },
      "createdAt": "2024-12-12T10:00:00+00:00",
      "releaseDate": "2024-12-12",
      "_links": {
        "self": {
          "href": "https://...",
          "type": "application/hal+json"
        },
        "payment": {
          "href": "https://...",
          "type": "application/hal+json"
        }
      }
    }
  ],
  "sequenceType": "oneoff",
  "subscriptionId": "sub_5B8cwPMGnU",
  "mandateId": "mdt_5B8cwPMGnU",
  "customerId": "cst_5B8cwPMGnU",
  "profileId": "pfl_5B8cwPMGnU",
  "settlementId": "stl_5B8cwPMGnU",
  "orderId": "ord_5B8cwPMGnU",
  "status": "open",
  "statusReason": {
    "code": "insufficient_funds",
    "message": "The account associated with the card has insufficient funds. The shopper should use another payment method or\ncontact their bank."
  },
  "isCancelable": true,
  "details": {
    "consumerName": "John Doe",
    "consumerAccount": "NL91ABNA0417164300",
    "consumerBic": "ABNANL2A",
    "cardNumber": "************1234",
    "bankName": "Mollie Bank",
    "bankAccount": "NL91ABNA0417164300",
    "bankBic": "ABNANL2A",
    "billingEmail": "customer@example.org",
    "transferReference": "...",
    "bizumReference": "2901tq2ure1d",
    "cardFingerprint": "...",
    "cardHolder": "John Doe",
    "cardAudience": "consumer",
    "cardLabel": "Mastercard",
    "cardCountryCode": "NL",
    "cardExpiryDate": "12/25",
    "cardFunding": "credit",
    "cardSecurity": "normal",
    "feeRegion": "maestro",
    "cardMaskedNumber": "...",
    "card3dsEci": "...",
    "cardBin": "...",
    "cardIssuer": "...",
    "failureReason": "card_declined",
    "failureMessage": "Your card was declined.",
    "wallet": "applepay",
    "paypalReference": "...",
    "paypalPayerId": "...",
    "sellerProtection": "ELIGIBLE",
    "paypalFee": {
      "currency": "EUR",
      "value": "10.00"
    },
    "customerReference": "...",
    "terminalId": "term_12345",
    "maskedNumber": "...",
    "creditorIdentifier": "...",
    "dueDate": "2025-01-01",
    "signatureDate": "2024-03-20",
    "bankReasonCode": "...",
    "bankReason": "...",
    "endToEndIdentifier": "...",
    "mandateReference": "...",
    "batchReference": "...",
    "fileReference": "...",
    "qrCode": {
      "height": 300,
      "width": 300,
      "src": "https://www.mollie.com/images/qr-code.png"
    },
    "voucherNumber": "...",
    "issuer": "...",
    "remainderAmount": {
      "currency": "EUR",
      "value": "10.00"
    },
    "remainderMethod": "creditcard"
  },
  "createdAt": "2024-03-20T09:13:37+00:00",
  "authorizedAt": "2024-03-20T09:28:37+00:00",
  "paidAt": "2024-03-20T09:28:37+00:00",
  "canceledAt": "2024-03-20T09:28:37+00:00",
  "expiresAt": "2024-03-20T09:28:37+00:00",
  "expiredAt": "2024-03-20T09:28:37+00:00",
  "failedAt": "2024-03-20T09:28:37+00:00",
  "dueDate": "2025-01-01",
  "storeCredentials": true,
  "_links": {
    "self": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "checkout": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "mobileAppCheckout": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "changePaymentState": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "dashboard": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "refunds": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "chargebacks": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "captures": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "settlement": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "customer": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "mandate": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "subscription": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "order": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "terminal": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "documentation": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "status": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "payOnline": {
      "href": "https://...",
      "type": "application/hal+json"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.