Create payment¶

Payments API v1

Warning

The v1 API has been deprecated. The v1 API will be supported for the foreseeable future, at least until July 2023. However, new features will only be added to the v2 API.

The documentation for creating payments in the new v2 API can be found here. For more information on the v2 API, refer to our v2 migration guide.

POSThttps://api.mollie.com/v1/payments

Authentication:API keys App access tokens

Payment creation is elemental to the Mollie API: this is where most payment implementations start off. Note optional parameters are accepted for certain payment methods.

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

Parameters¶

amountdecimalrequired

The amount in EUR that you want to charge, e.g. 100.00 if you would want to charge €100.00.

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

Note

If you want to charge other currencies, upgrade to the Create Payments v2 API. The v2 API fully supports multicurrency.

descriptionstringrequired

The description of the payment you are creating. This will be shown to the consumer on their card or bank statement when possible, and in any exports you generate.

We recommend you use the order number so that you can always link the payment to the order. 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.

Note

You can omit this parameter for payments with the sequenceType parameter set to recurring.

webhookUrlstringrequired

Set the webhook URL, where we will send payment status updates to.

Note

The webhookUrl must be reachable from Mollie’s point of view. If you want to use webhook during development on localhost, you should 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

methodstringoptional

Normally, a payment method selection screen is shown. However, when using this parameter, your customer will skip the selection screen and will be sent directly to the chosen payment method. The parameter enables you to fully integrate the payment method selection into your website, however note Mollie’s country based conversion optimization is lost.

Possible values: banktransfer belfius creditcard directdebit eps giftcard giropay ideal kbc mistercash 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 the Orders API instead.

metadatamixedoptional

Provide any data you like, and we will save the data alongside the payment. Whenever you fetch the payment with our API, we will also include the metadata. You can use up to approximately 1kB.

recurringTypestringoptional

Enables recurring payments. If set to first, a first payment for the customer is created, 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.

Possible values: first recurring

Warning

Using recurring payments with PayPal is only possible if PayPal has activated Reference Transactions on your merchant account. Check if you account is eligible via our Methods API. Make sure to set the recurringType parameter to first. Your account is eligible if you get PayPal as method returned.

customerIdstringoptional

The ID of the customer for whom the payment is being created. This is used for recurring payments and single-click payments.

mandateIdstringoptional

When creating recurring payments, the ID of a specific mandate may be supplied to indicate which of the consumer’s accounts should be credited.

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.

Bank transfer¶

billingEmailstringoptional

Consumer’s email address, to automatically send the bank transfer details to. Note: the payment instructions 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.

localestringoptional

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¶

billingAddressstringoptional

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

billingCitystringoptional

The card holder’s city.

billingRegionstringoptional

The card holder’s region.

billingPostalstringoptional

The card holder’s postal code.

billingCountrystringoptional

The card holder’s country in ISO 3166-1 alpha-2 format.

shippingAddressstringoptional

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

shippingCitystringoptional

The city of the shipping address.

shippingRegionstringoptional

The region of the shipping address.

shippingPostalstringoptional

The postal code of the shipping address.

shippingCountrystringoptional

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. These issuers are not dynamically available through the Issuers API, but can be retrieved by using the issuers include in the Methods API. If you need a brand not in the list, contact our support department. If only one issuer is activated on your account, you can omit this parameter.

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.

voucherPinstringoptional

The PIN code on the gift card. Only required if there is a PIN code printed on the gift card.

iDEAL¶

issuerstringoptional

An iDEAL issuer ID, for example ideal_INGBNL2A. The returned payment URL will deep-link into the specific banking website (ING Bank, in this example). The full list of issuers can be retrieved via the Issuers API.

KBC/CBC Payment Button¶

descriptionstringrequired

When KBC/CBC is chosen as the payment method, the description will be truncated to 13 characters.

issuerstringoptional

The issuer to use for the KBC/CBC payment. These issuers are not dynamically available through the Issuers API, but can be retrieved by using the issuers include in the Methods API.

Possible values: kbc cbc

PayPal¶

shippingAddressstringoptional

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

shippingCitystringoptional

The city of the shipping address. The maximum character length is 100.

shippingRegionstringoptional

The region of the shipping address. The maximum character length is 100. This field is required if the shippingCountry is one of the following countries: AR BR CA CN ID IN JP MX TH US

shippingPostalstringoptional

The postal code of the shipping address. The maximum character length is 20.

shippingCountrystringoptional

The country of the shipping address, in ISO 3166-1 alpha-2 format.

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.

Przelewy24¶

Note

Using the v1 API, only payments denominated in Euro can be created. Migrate to the v2 API to create payments in Polish złoty.

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.

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. Will pre-fill the beneficiary name in the checkout screen if present.

consumerAccountstringoptional

IBAN of the account holder. Only available if one-off payments are enabled on your account. Will pre-fill the IBAN in the checkout screen if present.

Access token parameters¶

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

profileIdstringrequiredShow details

The payment profile’s unique identifier, for example pfl_3RkSN1zuPE.

testmodebooleanoptionalShow details

Set this to true to make this payment a test payment.

applicationFeeobjectoptionalShow details

Adding an Application Fee allows you to charge the merchant for the payment and transfer this to your own account. Set the applicationFee parameter as a small object with its own amount and description. The application fee amount must be at least about €1.00 less than the payment’s amount parameter.

Show child parameters

amountdecimalrequired

The amount in EUR that the app wants to charge, e.g. 10.00 if the app would want to charge €10.00.

Note

You will need to invoice the merchant yourself. We will only collect the amount from the merchant and settle the amount with you.

descriptionstringrequired

The description of the application fee. This will appear on settlement reports to the merchant and to you.

The maximum length is 255 characters.

QR codes¶

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

POST https://api.mollie.com/v1/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/json

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

Example¶

Request¶

curl -X POST https://api.mollie.com/v1/payments \
    -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
    -d "amount=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"

Response¶

HTTP/1.1 201 Created
Content-Type: application/json

{
    "resource": "payment",
    "id": "tr_7UhSN1zuXS",
    "mode": "test",
    "createdDatetime": "2018-03-16T14:36:44.0Z",
    "status": "open",
    "expiryPeriod": "PT15M",
    "amount": "10.00",
    "description": "Order #12345",
    "metadata": {
        "order_id": "12345"
    },
    "locale": "nl_NL",
    "profileId": "pfl_QkEhN94Ba",
    "links": {
        "paymentUrl": "https://www.mollie.com/payscreen/select-method/7UhSN1zuXS",
        "redirectUrl": "https://webshop.example.org/order/12345/",
        "webhookUrl": "https://webshop.example.org/payments/webhook/"
    }
}