Create payment

Payments API v2
POSThttps://api.mollie.com/v2/payments

Payment creation is elemental to the Mollie API: this is where most payment implementations start off.

Once you have created a payment, you should redirect your customer to the URL in the _links.checkout property from the response.

To wrap your head around the payment process, an explanation and flow charts can be found in the Accepting payments guide.

Note

Optional parameters are accepted for certain payment methods.

Parameters

amountamount objectrequired

The amount that you want to charge, e.g. {"currency":"EUR", "value":"1000.00"} if you would want to charge €1000.00.

You can find the minimum and maximum amounts per payment method in our help center. Additionally, they can be retrieved using Get payment method.

Show child parameters

currencystringrequired
An ISO 4217 currency code. The currencies supported depend on the payment methods that are enabled on your account.
valuestringrequired
A string containing the exact amount you want to charge in the given currency. Make sure to send the right amount of decimals and omit the thousands separator. Non-string values are not accepted.
descriptionstringrequired

The description of the payment you are creating. This 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.

redirectUrlstringrequired

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 can be omitted for recurring payments (sequenceType: recurring) and for Apple Pay payments with an applePayPaymentToken.

cancelUrlstringoptional

The URL your consumer will be redirected to when the consumer explicitly cancels the payment. If this URL is not provided, the consumer 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 consumer-facing flow to handle payment cancellations.

The parameter can be omitted for recurring payments (sequenceType: recurring) and for Apple Pay payments with an applePayPaymentToken.

webhookUrlstringoptional

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

localestringoptional

Allows you to preset the language to be used in the hosted payment pages shown to the consumer. 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 following languages:

Possible values: en_US en_GB nl_NL nl_BE fr_FR fr_BE de_DE de_AT de_CH es_ES ca_ES pt_PT it_IT nb_NO sv_SE fi_FI da_DK is_IS hu_HU pl_PL lv_LV lt_LT

methodstring|arrayoptional

Normally, a payment method screen is shown. However, when using this parameter, you can choose a specific payment method and your customer will skip the selection screen and is sent directly to the chosen payment method. The parameter enables you to fully integrate the payment method selection into your website.

You can also specify the methods in an array. By doing so we will still show the payment method selection screen but will only show the methods specified in the array. For example, you can use this functionality to only show payment methods from a specific country to your customer ['bancontact', 'belfius'].

Possible values: applepay bancontact banktransfer belfius creditcard directdebit eps giftcard giropay ideal kbc mybank paypal paysafecard przelewy24 sofort

Note

If you are looking to create payments with the Klarna Pay now, Klarna Pay later, Klarna Slice it, in3 or voucher payment methods, use Create order instead.

restrictPaymentMethodsToCountrystringoptional
metadatamixedoptional

Parameters for recurring payments

Recurring payments are created through the Payments API by providing a sequenceType. For the recurring sequence type, you have to provide a customerId to indicate which account you want to charge. You can charge a card by providing a mandateId. See our guide on Recurring for more information.

sequenceTypestringrequired for recurring
customerIdstringrequired
mandateIdstringoptional

Parameters for pre-authorized payments

Note

Pre-authorization is currently in beta.

Pre-authorized payments are created through the Payments API by providing a captureMode. With the manual capture mode, you decide when to capture the funds. See our guide on Placing a hold for a payment for more information.

captureModestringoptional

Indicates whether the capture will be scheduled automatically or not. Set to manual to capture the payment manually using the Create capture endpoint.

Set to automatic by default, which indicates the payment will be captured automatically, without having to separately request it. Setting automatic without a captureDelay will result in a regular payment.

Possible values: automatic manual

captureDelaystringoptional

Interval to wait before the payment is captured, for example 8 hours or 2 days. In order to schedule an automatic capture, the captureMode must be set to either automatic or be omitted.

Possible values: ... hours ... days

Note

The maximum delay is 7 days (168 hours).

Payment method-specific parameters

If you specify the method parameter, optional parameters may be available for the payment method. If no method is specified, you can still send the optional parameters and we will apply them when the consumer selects the relevant payment method.

Apple Pay

applePayPaymentTokenstringoptional

The Apple Pay Payment Token object (encoded as JSON) that is part of the result of authorizing a payment request. The token contains the payment information needed to authorize the payment.

The object should be passed encoded in a JSON string. Example:

{"paymentData": {"version": "EC_v1", "data": "vK3BbrCbI/...."}}

For documentation on how to get this token, see Direct integration of Apple Pay.

Bank transfer

billingEmailstringoptional
Consumer’s email address, to automatically send the bank transfer details to. Note: the payment instructions will will be sent immediately when creating the payment. If you do not specify the locale parameter, the email will be sent in English, as we haven’t yet been able to detect the consumer’s browser language.
dueDatestringoptional

The date the payment should expire, in YYYY-MM-DD format. Note: the minimum date is tomorrow and the maximum date is 100 days after tomorrow.

After you created the payment, you can still update the dueDate via Update payment.

localestringoptional

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: en_US en_GB nl_NL nl_BE fr_FR fr_BE de_DE de_AT de_CH es_ES ca_ES pt_PT it_IT nb_NO sv_SE fi_FI da_DK is_IS hu_HU pl_PL lv_LV lt_LT

Credit card

billingAddressaddress objectoptional

The card holder’s address details. We advise to provide these details to improve the credit card fraud protection, and thus improve conversion.

If an address is provided, then the address has to be in a valid format. See the address object documentation for more information on which formats are accepted.

Show child parameters

streetAndNumberstringrequired
The card holder’s street and street number.
postalCodestringconditional
The card holder’s postal code. This field is required if the provided country has a postal code system.
citystringrequired
The card holder’s city.
regionstringoptional
The card holder’s region.
countrystringrequired
The card holder’s country in ISO 3166-1 alpha-2 format.
cardTokenstringoptional
The card token you got from Mollie Components. The token contains the card information (such as card holder, card number, and expiry date) needed to complete the payment.
shippingAddressaddress objectoptional

The shipping address details. We advise to provide these details to improve the credit card fraud protection, and thus improve conversion.

If an address is provided, then the address has to be in a valid format. See the address object documentation for more information on which formats are accepted.

Show child parameters

streetAndNumberstringrequired
The street and street number of the shipping address.
postalCodestringconditional
The postal code of the shipping address. This field is required if the provided country has a postal code system.
citystringrequired
The city of the shipping address.
regionstringoptional
The region of the shipping address.
countrystringrequired
The country of the shipping address in ISO 3166-1 alpha-2 format.

Gift cards

issuerstringoptional

The gift card brand to use for the payment. This is useful when you want to embed the gift card type selection on your own checkout screen. The issuers can be retrieved by using the issuers include in the Methods API.

If you need a brand that is not in the list, contact our support department. We can also support closed-loop cards.

Possible values: beautycadeaukaart bloemencadeaukaart bloemplantgiftcard boekenbon dagiftcard decadeaukaart delokalecadeaukaart dinercadeau doenkadotickets fashioncheque festivalcadeau good4fun horseandgifts huistuincadeaukaart jewelcard kluscadeau kunstencultuurcadeaukaart nationalebioscoopbon nationaleentertainmentcard nationalegolfbon ohmygood podiumcadeaukaart reiscadeau restaurantcadeau shoesandsneakerscadeau sodexosportculturepass sportenfitcadeau sustainablefashion travelcheq vvvgiftcard vvvdinercheque vvvlekkerweg webshopgiftcard wijncadeaukaart yourgift

voucherNumberstringoptional
The card number on the gift card. You can supply this to prefill the card number.
voucherPinstringoptional
The PIN code on the gift card. You can supply this to prefill the PIN, if the card has any.

iDEAL

issuerstringoptional
An iDEAL issuer ID, for example ideal_INGBNL2A. This is useful when you want to embed the issuer selection on your own checkout screen. When supplying an issuer ID, the returned payment URL will deep-link to the specific banking website (ING Bank, in this example). The full list of issuers can be retrieved via the Methods API by using the optional issuers include.

KBC/CBC Payment Button

descriptionstringoptional
For the KBC/CBC payment method the description will be truncated to 13 characters.
issuerstringoptional

The issuer to use for the KBC/CBC payment. This is useful when you want to embed the selection between KBC and CBC on your own checkout screen. The full list of issuer IDs can be retrieved via the Methods API by using the optional issuers include.

Possible values: kbc cbc

Klarna

Note

Klarna payments can only be created via the Orders API.

extraMerchantDataobjectoptional

For some industries, additional purchase information can be sent to Klarna to increase the authorization rate. You can submit your extra data in this field if you have agreed upon this with Klarna. This field should be an object containing any of the allowed keys and sub objects described at the Klarna Developer Documentation under attachment.body.

Reach out to your account manager at Mollie to enable this feature with Klarna, and to agree on which fields you can send.

Klarna Pay now. / Pay later. / Slice it.

Note

Klarna payments can only be created via the Orders API.

extraMerchantDataobjectoptional

For some industries, additional purchase information can be sent to Klarna to increase the authorization rate. You can submit your extra data in this field if you have agreed upon this with Klarna. This field should be an object containing any of the allowed keys and sub objects described at the Klarna Developer Documentation under attachment.body.

Reach out to your account manager at Mollie to enable this feature with Klarna, and to agree on which fields you can send.

Billie

Note

Billie payments can only be created via the Orders API.

billingAddressaddress objectoptional

Company address details. We advise to provide these details to improve the Billie’s risk system.

If an address is provided, then the address has to be in a valid format. See the address object documentation for more information on which formats are accepted.

Show child parameters

organizationNamestringrequired
The organization’s name. It is mandatory for Billie orders.
givenNamestringrequired
The given name (first name) of the buyer.
familyNamestringrequired
The family name (surname) of the buyer.
emailstringrequired
The contact email address of the organization.
streetAndNumberstringrequired
streetAdditionalstringoptional
postalCodestringconditional
This field is required if the provided country has a postal code system.
citystringrequired
regionstringoptional
countrystringrequired
The country of the address in ISO 3166-1 alpha-2 format.
companyobjectoptional

Billie is a B2B payment method, thus it requires some extra information to identify the business that is creating the order. It is recommended to include these parameters as part of the create order request for a seamless flow, otherwise the customer will be asked to fill the missing fields at the Billie’s checkout page.

Show child parameters

registrationNumberstringoptional
Organization’s registration number.
vatNumberstringoptional
Organization’s VAT number.
entityTypestringoptional
Organization’s entity type. Must be one of: limited-company, public-limited-company, entrepreneurial-company, limited-partnership-limited-company, limited-partnership, general-partnership, registered-sole-trader, sole-trader, civil-law-partnership, public-institution

PayPal

descriptionstringoptional

For PayPal, we will automatically try to determine the order number from the description string and pass it on to PayPal as the invoice reference. This field is searchable in the PayPal merchant dashboard.

For example, in the string Best Service Order ABS123 our system will assume “Order ABS123” to be the invoice reference.

This functionality is a ‘best effort’ feature based on a list of common keywords like ‘order’, ‘payment’, ‘invoice’, and common translations like ‘Zahlung’ and ‘Pedido’.

shippingAddressaddress objectoptional

The shipping address details. We advise to provide these details to improve PayPal’s fraud protection, and thus improve conversion.

If an address is provided, then the address has to be in a valid format. See the address object documentation for more information on which formats are accepted.

Show child parameters

givenNamestringrequired
The given name (first name) of the person. The maximum character length of givenName and familyName combined is 128.
familyNamestringrequired
The family name (surname) of the person. The maximum character length of givenName and familyName combined is 128.
streetAndNumberstringrequired
The street and street number of the shipping address. The maximum character length is 128.
postalCodestringconditional
The postal code of the shipping address. This field is required if the provided country has a postal code system. The maximum character length is 20.
citystringrequired
The city of the shipping address. The maximum character length is 100.
regionstringoptional
The region of the shipping address. The maximum character length is 100. Note: this field is required if country is one of the following countries: AR BR CA CN ID IN JP MX TH US
countrystringrequired
The country of the shipping address in ISO 3166-1 alpha-2 format.
sessionIdstringoptional

The unique ID you have used for the PayPal fraud library. You should include this if you use PayPal for an on-demand payment. The maximum character length is 32.

Refer to the Recurring payments guide for more information on how to implement the fraud library.

digitalGoodsbooleanoptional

Indicate if you are about to deliver digital goods, like for example a license. Setting this parameter can have consequences for your Seller Protection by PayPal. See PayPal’s help article about Seller Protection for more information.

Default: false

paysafecard

customerReferencestringoptional

Used for consumer identification. Use the following guidelines to create your customerReference:

  • Has to be unique per shopper
  • Has to remain the same for one shopper
  • Should be as disconnected from personal data as possible
  • Must not contain customer sensitive data
  • Must not contain the timestamp
  • Must not contain the IP address

Due to data privacy regulations, make sure not to use any personal identifiable information in this parameter.

If not provided, Mollie will send a hashed version of the shopper IP address.

Point-of-sale

terminalIdstringrequired
The unique identifier used for referring to a terminal. This ID is used for assigning the payment to a specific terminal and it can be retrieved via List terminals. For more information about point-of-sale payments, please check our guide point-of-sale payments.

Przelewy24

billingEmailstringoptional
Consumer’s email address.

SEPA Direct Debit

Note

One-off SEPA Direct Debit payments using Mollie Checkout can only be created if this is enabled on your account. In general, it is not very useful for webshops but may be useful for charities.

Contact our support department to enable this.

If you want to use recurring payments, take a look at our Recurring payments guide.

consumerNamestringoptional
Beneficiary name of the account holder. Only available if one-off payments are enabled on your account. Supplying this field will pre-fill the beneficiary name in the checkout screen.
consumerAccountstringoptional
IBAN of the account holder. Only available if one-off payments are enabled on your account. Supplying this field will pre-fill the IBAN in the checkout screen.

Vouchers

issuerstringoptional
A voucher issuer ID, for example sodexo-lunchpass. If you supply this parameter, the returned payment URL will deep-link to the specific card website. The full list of issuers can be retrieved via the Methods API by using the optional issuers include.

Access token parameters

If you are using organization access tokens or are creating an OAuth app, you have to specify which profile you are creating the payment for using the profileId parameter. Organizations can have multiple profiles for each of their websites. See Profiles API for more information.

For these authentication methods the optional testmode parameter is available as well to enable test mode.

profileIdstringrequired for access tokens
testmodebooleanoptional

Mollie Connect parameters

With Mollie Connect you can charge fees on payments that are processed through your app, either by defining an application fee or by splitting the payment. To learn more about the difference, refer to the Mollie Connect overview.

applicationFeeobjectoptional
routingarrayoptional

QR codes

To create a payment with a QR code embedded in the API response, explicitly set the payment method and call the API endpoint with an include request for details.qrCode in the query string:

POSThttps://api.mollie.com/v2/payments?include=details.qrCode

QR codes can be generated for iDEAL, Bancontact and bank transfer payments.

Refer to the Get payment reference to see what the API response looks like when the QR code is included.

Response

201 application/hal+json

A payment object is returned, as described in Get payment.

Example

cURLPHPPythonRubyNode.js
1
2
3
4
5
6
7
8
curl -X POST https://api.mollie.com/v2/payments \
   -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
   -d "amount[currency]=EUR" \
   -d "amount[value]=10.00" \
   -d "description=Order #12345" \
   -d "redirectUrl=https://webshop.example.org/order/12345/" \
   -d "webhookUrl=https://webshop.example.org/payments/webhook/" \
   -d "metadata={\"order_id\": \"12345\"}"
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");
$payment = $mollie->payments->create([
      "amount" => [
            "currency" => "EUR",
            "value" => "10.00" // You must send the correct number of decimals, thus we enforce the use of strings
      ],
      "description" => "Order #12345",
      "redirectUrl" => "https://webshop.example.org/order/12345/",
      "webhookUrl" => "https://webshop.example.org/payments/webhook/",
      "metadata" => [
            "order_id" => "12345",
      ],
]);
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from mollie.api.client import Client

mollie_client = Client()
mollie_client.set_api_key("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM")
payment = mollie_client.payments.create({
    "amount": {
        "currency": "EUR",
        "value": "10.00",
    },
    "description": "Order #12345",
    "redirectUrl": "https://webshop.example.org/payments/webhook/",
    "webhookUrl": "https://webshop.example.org/order/12345/",
    "metadata": {
        "order_id": "12345",
    }
})
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
require 'mollie-api-ruby'

Mollie::Client.configure do |config|
  config.api_key = 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM'
end

payment = Mollie::Payment.create(
  amount: {
    currency: 'EUR',
    value: '10.00'
  },
  description: 'Order #12345',
  redirect_url: 'https://webshop.example.org/order/12345/',
  webhook_url: 'https://webshop.example.org/payments/webhook/',
  metadata: {
    order_id: '12345'
  }
)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const { createMollieClient } = require('@mollie/api-client');
const mollieClient = createMollieClient({ apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

const payment = await mollieClient.payments.create({
  amount: {
    currency: 'EUR',
    value: '10.00'
  },
  description: 'Order #12345',
  redirectUrl: 'https://webshop.example.org/order/12345/',
  webhookUrl: 'https://webshop.example.org/payments/webhook/',
  metadata: {
    order_id: '12345'
  }
});

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
33
34
35
36
37
38
39
40
41
42
43
44
HTTP/1.1 201 Created
Content-Type: application/hal+json

{
    "resource": "payment",
    "id": "tr_7UhSN1zuXS",
    "mode": "test",
    "createdAt": "2018-03-20T09:13:37+00:00",
    "amount": {
        "value": "10.00",
        "currency": "EUR"
    },
    "description": "Order #12345",
    "method": null,
    "metadata": {
        "order_id": "12345"
    },
    "status": "open",
    "isCancelable": false,
    "expiresAt": "2018-03-20T09:28:37+00:00",
    "details": null,
    "profileId": "pfl_QkEhN94Ba",
    "sequenceType": "oneoff",
    "redirectUrl": "https://webshop.example.org/order/12345/",
    "webhookUrl": "https://webshop.example.org/payments/webhook/",
    "_links": {
        "self": {
            "href": "https://api.mollie.com/v2/payments/tr_7UhSN1zuXS",
            "type": "application/json"
        },
        "checkout": {
            "href": "https://www.mollie.com/payscreen/select-method/7UhSN1zuXS",
            "type": "text/html"
        },
        "dashboard": {
            "href": "https://www.mollie.com/dashboard/org_12345678/payments/tr_7UhSN1zuXS",
            "type": "text/html"
        },
        "documentation": {
            "href": "https://docs.mollie.com/reference/v2/payments-api/create-payment",
            "type": "text/html"
        }
    }
}