Create payment
Payments API

POST
https://api.mollie.nl/v1/payments
Authentication: API keys OAuth 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 Overview.

Parameters

amount
decimal

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

description
string

The description of the payment you're 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 particulary useful for bookkeeping.

redirectUrl
string

The URL the consumer 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 the consumer returns.

webhookUrl
string

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

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

metadata
object

Optional – Provide any data you like in JSON notation, and 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 1kB of JSON.

locale
string

Optional – Allow you to preset the language to be used in the payment screens shown to the consumer. When this parameter is not provided, the browser language will be used instead (which is usually more accurate). You can provide any ISO 15897 locale, but our payment screens currently only support the following languages:

Possible values: en_US de_AT de_CH de_DE es_ES fr_BE fr_FR nl_BE nl_NL

recurringType
string

Optional – Learn more about the recurringType parameter.

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. Learn more here.

mandateId
string

Optional – When creating recurring payments, a specific mandate ID 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.

issuer
string

Optional – An iDEAL issuer ID, for example ideal_INGNL2A. The returned payment URL will deep-link into the specific banking website (ING Bank, in this example). For a list of issuers, refer to the Issuers API.

billingAddress
string

Optional – The card holder's address. We advise to provide these details to improve the credit card fraude protection, and thus improve conversion.

billingCity
string

Optional – The card holder's city.

billingRegion
string

Optional – The card holder's region.

billingPostal
string

Optional – The card holder's postal code.

billingCountry
string

Optional – The card holder's country in ISO 3166-1 alpha-2 format.

shippingAddress
string

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

shippingCity
string

Optional – The city of the shipping address.

shippingRegion
string

Optional – The region of the shipping address.

shippingPostal
string

Optional – The postal code of the shipping address.

shippingCountry
string

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

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.

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 de_AT de_CH de_DE es_ES fr_BE fr_FR nl_BE nl_NL

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 web shops but may be useful for charities.

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

consumerName
string

Only if enabled in your account for one-off payments – Beneficiary name of the account holder. Will be pre-filled in the checkout if sent.

consumerAccount
string

Only if enabled in your account for one-off payments – IBAN of the account holder. Will be pre-filled in the checkout if sent.

shippingAddress
string

Optional – The shipping address. We advise to provide these details to improve PayPal's fraude protection, and thus improve conversion. The maximum character length is 128.

shippingCity
string

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

shippingRegion
string

Optional – 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

shippingPostal
string

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

shippingCountry
string

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

customerReference
string

Optional – Used for consumer identification. For example, you could use the consumer's IP address.

billingEmail
string

Optional – Customer's email address. This is used when handling invalid transactions (wrong amount transferred, transfer of expired or cancelled payments, et cetera).

description
string

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

issuer
string

Optional – The issuer to use for the KBC/CBC payment. Can be either kbc or cbc. These issuers are not dynamically available through the issuers API, but can be retrieved by using the issuers include in the Methods API.

billingEmail
string

Optional – Consumer's email address. We will use this to send a new gift card when you refund (part) of the gift card payment. If you want to use refunds, this parameter is mandatory.

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.

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 to which profile the payment belongs. Organizations can have multiple profiles for each of their websites. See Profiles API for more.

profileId
string

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. Set the applicationFee parameter as a small object with it’s own amount and description. The application fee amount must be at least €1.00 less than the payment's amount parameter.

amount
decimal

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

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

description
string

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

Includes

Some endpoints allow you to indicate if you want more information to be included in the API response via the include querystring parameter.

  • details.qrCode Include a QR code object (only available for iDEAL, Bitcoin and bank transfer payments).

Response

201
application/json; charset=utf-8

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

Example

Request code

require_once 'Mollie/API/Autoloader.php';

$mollie = new Mollie_API_Client;
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');

try
{
    $payment = $mollie->payments->create(
        array(
            'amount'      => 10.00,
            'description' => 'My first payment',
            'redirectUrl' => 'https://webshop.example.org/order/12345/',
            'webhookUrl'  => 'https://webshop.example.org/payments/webhook/',
            'metadata'    => array(
                'order_id' => '12345'
            )
        )
    );

    /*
     * Send the customer off to complete the payment.
     */
    header("Location: " . $payment->getPaymentUrl());
    exit;
}
catch (Mollie_API_Exception $e)
{
    echo "API call failed: " . htmlspecialchars($e->getMessage());
    echo " on field " . htmlspecialchars($e->getField());
}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "resource":        "payment",
    "id":              "tr_7UhSN1zuXS",
    "mode":            "test",
    "createdDatetime": "2017-12-15T18:40:53.0Z",
    "status":          "open",
    "expiryPeriod":    "PT15M",
    "amount":          10.00,
    "description":     "My first payment",
    "metadata": {
        "order_id": "12345"
    },
    "locale": "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/"
    }
}