Create payment¶
POST
https://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¶
amount
amount objectrequiredThe 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.
currency
stringrequiredvalue
stringrequireddescription
stringrequiredThe 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.
redirectUrl
stringrequiredThe 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
.
cancelUrl
stringoptionalThe 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
.
webhookUrl
stringoptionalSet 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.
locale
stringoptionalAllows 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
method
string|arrayoptionalNormally, 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.
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.
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.
Indicate which type of payment this is in a recurring sequence. If set to first
, a
first payment is created for the customer, allowing the customer to agree
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.
Possible values: oneoff
first
recurring
For PayPal payments, recurring is only possible if PayPal has activated Reference Transactions on your merchant
account. Check if you account is eligible via our Methods API with
parameter sequenceType
set to first
. Your account is eligible if PayPal is returned in the method list.
The ID of the customer for whom the payment is being created. This is used primarily for recurring payments, but can also be used on regular payments to enable single-click payments.
This field needs to be provided for payments with the recurring
sequence type.
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.
captureMode
stringoptionalIndicates 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
captureDelay
stringoptionalInterval 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¶
applePayPaymentToken
stringoptionalThe 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¶
billingEmail
stringoptionallocale
parameter, the email will be
sent in English, as we haven’t yet been able to detect the consumer’s browser language.dueDate
stringoptionalThe 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.
locale
stringoptionalFor 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¶
billingAddress
address objectoptionalThe 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.
streetAndNumber
stringrequiredpostalCode
stringconditionalcountry
has a postal code system.city
stringrequiredregion
stringoptionalcountry
stringrequiredcardToken
stringoptionalshippingAddress
address objectoptionalThe 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.
streetAndNumber
stringrequiredpostalCode
stringconditionalcountry
has a postal code
system.city
stringrequiredregion
stringoptionalcountry
stringrequiredGift cards¶
issuer
stringoptionalThe 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
voucherNumber
stringoptionalvoucherPin
stringoptionaliDEAL¶
issuer
stringoptionalideal_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¶
description
stringoptionalissuer
stringoptionalThe 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.
extraMerchantData
objectoptionalFor 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.
extraMerchantData
objectoptionalFor 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.
billingAddress
address objectoptionalCompany 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.
organizationName
stringrequiredgivenName
stringrequiredfamilyName
stringrequiredemail
stringrequiredstreetAndNumber
stringrequiredstreetAdditional
stringoptionalpostalCode
stringconditionalcountry
has a postal code system.city
stringrequiredregion
stringoptionalcountry
stringrequiredcompany
objectoptionalBillie 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.
registrationNumber
stringoptionalvatNumber
stringoptionalentityType
stringoptionallimited-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¶
description
stringoptionalFor 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’.
shippingAddress
address objectoptionalThe 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.
givenName
stringrequiredgivenName
and familyName
combined is 128.familyName
stringrequiredgivenName
and familyName
combined
is 128.streetAndNumber
stringrequiredpostalCode
stringconditionalcountry
has a postal code
system. The maximum character length is 20.city
stringrequiredregion
stringoptionalcountry
is one of the following countries: AR
BR
CA
CN
ID
IN
JP
MX
TH
US
country
stringrequiredsessionId
stringoptionalThe 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.
digitalGoods
booleanoptionalIndicate 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¶
customerReference
stringoptionalUsed 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¶
terminalId
stringrequiredPrzelewy24¶
billingEmail
stringoptionalSEPA 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.
consumerName
stringoptionalconsumerAccount
stringoptionalVouchers¶
issuer
stringoptionalsodexo-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.
pfl_3RkSN1zuPE
.true
to make this payment a test payment.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.
Adding an application fee allows you to charge the merchant a small sum for the payment and transfer this to your own account.
amount
amount objectrequiredThe fee that the app wants to charge, e.g. {"currency":"EUR", "value":"10.00"}
if the app would want to charge
€10.00.
There need to be enough funds left from the payment to deduct the Mollie payment fees as well. For example, you cannot charge a €0.99 fee on a €1.00 payment. The API will return an error if the requested application fee is too high for the specific payment amount and method.
currency
stringrequiredvalue
stringrequireddescription
stringrequiredThe description of the application fee. This will appear on settlement reports to the merchant and to you.
The maximum length is 255 characters.
Note
Split Payments are not enabled by default. To enable them for your organization, reach out to our partner management team.
An optional routing configuration which enables you to route a successful payment, or part of the payment, to one or more connected accounts. Additionally, you can schedule (parts of) the payment to become available on the connected account on a future date.
See the Split payments guide for more information on payment routing.
If a routing array is supplied, it must contain one or more routing objects with the following parameters.
amount
amount objectconditionalIf more than one routing object is given, the routing objects must indicate what portion of the total payment amount is being routed.
currency
stringrequiredEUR
payments can be
routed.value
stringrequireddestination
objectrequiredThe destination of this portion of the payment.
type
stringrequiredThe type of destination. Currently only the destination type organization
is supported.
Possible values: organization
organizationId
stringconditionalRequired for destination type organization
. The ID of the connected organization the funds should be routed
to, for example org_12345
.
Note: me
or the ID of the current organization are not accepted as an organizationId
. After all
portions of the total payment amount have been routed, the amount left will be routed to the current
organization automatically.
releaseDate
dateoptionalOptionally, schedule this portion of the payment to be transferred to its destination on a later date. The date
must be given in YYYY-MM-DD
format.
If no date is given, the funds become available to the balance as soon as the payment succeeds.
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:
POST
https://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.
Example¶
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" } } } |