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

Parameters

amount

object
required

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

currency

string
required
An ISO 4217 currency code. The currencies supported depend on the payment methods that are enabled on your account.

value

string
required
A string containing the exact amount you want to charge in the given currency. Make sure to send the right amount of decimals. Non-string values are not accepted.

description

string
required

The description of the payment you’re creating. This will be shown to the consumer 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. This is particularly useful for bookkeeping.

redirectUrl

string
required

The URL the 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

For payments with sequenceType recurring, you can skip this parameter. For all other payments, this parameter is required.

webhookUrl

string
required

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

Note

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

string
optional

Allows you to preset the language to be used in the payment screens 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 ISO 15897 locale, but our payment screen currently only supports the following languages:

Possible values: en_US 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
optional

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: bancontact banktransfer belfius bitcoin creditcard directdebit eps giftcard giropay ideal inghomepay kbc paypal paysafecard sofort

metadata

mixed
optional
Provide any data you like, for example a string or a JSON object. We will save the data alongside the payment. Whenever you fetch the payment with our API, we’ll also include the metadata. You can use up to approximately 1kB.

sequenceType

string
optional

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 (see also: Recurring).

Possible values: oneoff first recurring

customerId

string
optional
The ID of the Customer for whom the payment is being created. This is used for recurring payments and single click payments.

mandateId

string
optional
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

billingEmail

string
optional
Consumer’s email address, to automatically send the bank transfer details to. Please note: the payment instructions will be sent immediately when creating the payment. If you don’t 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.

dueDate

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

locale

string
optional

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

Possible values: en_US 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

Bitcoin

billingEmail

string
optional
The email address of the customer. This is used when handling invalid transactions (wrong amount transferred, transfer of expired or canceled payments, et cetera).

Credit card

billingAddress

address object
optional

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

The following fields can be added to the object:

streetAndNumber

string
optional
The card holder’s street and street number.

postalCode

string
optional
The card holder’s postal code.

city

string
optional
The card holder’s city.

region

string
optional
The card holder’s region.

country

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

Please refer to the documentation of the address object for more information on which inputs are accepted inputs.

shippingAddress

address object
optional

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

The following fields can be added to the object:

streetAndNumber

string
optional
The street and street number of the shipping address.

postalCode

string
optional
The postal code of the shipping address.

city

string
optional
The city of the shipping address.

region

string
optional
The region of the shipping address.

country

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

Please refer to the documentation of the address object for more information on which inputs are accepted inputs.

Gift cards

issuer

string
optional

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: nationalebioscoopbon nationaleentertainmentcard kunstencultuurcadeaukaart podiumcadeaukaart vvvgiftcard webshopgiftcard yourgift

voucherNumber

string
optional
The card number on the gift card.

voucherPin

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

iDEAL

issuer

string
optional
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 Methods API by using the optional issuers include.

KBC/CBC Payment Button

description

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

issuer

string
optional

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

description

string
required

If a description in the form Order <order number> is used, the order number is passed to PayPal as the invoice reference. This field is searchable in the PayPal merchant dashboard. Alternatively, we will recognize the following keywords:

  • Cart
  • Order
  • Invoice
  • Payment

shippingAddress

address object
optional

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

The following fields can be added to the object:

streetAndNumber

string
optional
The street and street number of the shipping address. The maximum character length is 128.

postalCode

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

city

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

region

string
optional
The region of the shipping address. The maximum character length is 100. Please note: this field is required if country is one of the following countries: AR BR CA CN ID IN JP MX TH US

country

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

Please refer to the documentation of the address object for more information on which inputs are accepted inputs.

paysafecard

customerReference

string
optional
Used for consumer identification. For example, you could use the consumer’s IP 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.

consumerName

string
optional
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.

consumerAccount

string
optional
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.

Mollie Connect/OAuth parameters

If you’re creating an app with Mollie Connect/OAuth, 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.

profileId

string
required
The payment profile’s unique identifier, for example pfl_3RkSN1zuPE. This field is mandatory.

testmode

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

applicationFee

object
optional

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 object
required

The amount in that the app wants to charge, e.g. {"currency":"EUR", "value":"10.00"} if the app would want to charge €10.00.

currency

string
required
An ISO 4217 currency code.

value

string
required
A string containing the exact amount you want to charge in the given currency. Make sure to send the right amount of decimals. Non-string values are not accepted.

description

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

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:

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

QR codes can be generated for iDEAL, Bitcoin, 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; charset=utf-8

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

Example

Request (curl)

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=My first payment" \
    -d "redirectUrl=https://webshop.example.org/order/12345/" \
    -d "webhookUrl=https://webshop.example.org/payments/webhook/" \
    -d "metadata={\"order_id\": \"12345\"}"

Request (PHP)

 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" => "My first payment",
   "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
HTTP/1.1 201 Created
Content-Type: application/hal+json; charset=utf-8

{
    "resource": "payment",
    "id": "tr_7UhSN1zuXS",
    "mode": "test",
    "createdAt": "2018-03-20T09:13:37+00:00",
    "amount": {
        "value": "10.00",
        "currency": "EUR"
    },
    "description": "My first payment",
    "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"
        },
        "documentation": {
            "href": "https://docs.mollie.com/reference/v2/payments-api/create-payment",
            "type": "text/html"
        }
    }
}