PaymentRequest.md

PaymentRequest

Fields

Field	Type	Required	Description	Example
description	String	✔️	The description of the payment. 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.	Chess Board
amount	Amount	✔️	In v2 endpoints, monetary amounts are represented as objects with a currency and value field.
redirectUrl	Optional<String>	✔️	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 is normally required, but can be omitted for recurring payments (sequenceType: recurring) and for Apple Pay payments with an applePayPaymentToken.	https://example.org/redirect
cancelUrl	JsonNullable<String>	➖	The URL your customer will be redirected to when the customer explicitly cancels the payment. If this URL is not provided, the customer 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 customer-facing flow to handle payment cancellations.	https://example.org/cancel
webhookUrl	JsonNullable<String>	➖	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.	https://example.org/webhooks
lines	List<PaymentRequestLines>	➖	Optionally provide the order lines for the payment. Each line contains details such as a description of the item ordered and its price. All lines must have the same currency as the payment. Required for payment methods billie, in3, klarna, riverty and voucher.
billingAddress	Optional<PaymentRequestBillingAddress>	➖	The customer's billing address details. We advise to provide these details to improve fraud protection and conversion. Should include email or a valid postal address consisting of streetAndNumber, postalCode, city and country. Required for payment method alma, in3, klarna, billie and riverty.
shippingAddress	Optional<PaymentAddress>	➖	N/A
locale	JsonNullable<Locale>	➖	Allows you to preset the language to be used.	en_US
method	JsonNullable<PaymentRequestMethod>	➖	N/A
issuer	JsonNullable<String>	➖	Only relevant for iDEAL, KBC/CBC, gift card, and voucher payments. ⚠️ With the introduction of iDEAL 2 in 2025, this field will be ignored for iDEAL payments. For more information on the migration, refer to our help center. Some payment methods are a network of connected banks or card issuers. In these cases, after selecting the payment method, the customer may still need to select the appropriate issuer before the payment can proceed. We provide hosted issuer selection screens, but these screens can be skipped by providing the issuer via the API up front. The full list of issuers for a specific method can be retrieved via the Methods API by using the optional issuers include. A valid issuer for iDEAL is for example ideal_INGBNL2A (for ING Bank).	ideal_INGBNL2A
restrictPaymentMethodsToCountry	JsonNullable<String>	➖	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.	NL
metadata	JsonNullable<Metadata>	➖	Provide any data you like, for example a string or a JSON object. We will save the data alongside the entity. Whenever you fetch the entity with our API, we will also include the metadata. You can use up to approximately 1kB.
captureMode	JsonNullable<CaptureMode>	➖	Indicate if the funds should be captured immediately or if you want to place a hold and capture at a later time. This field needs to be set to manual for method riverty.	manual
captureDelay	JsonNullable<String>	➖	Only relevant if you wish to manage authorization and capturing separately. Some payment methods allow placing a hold on the card or bank account. This hold or 'authorization' can then at a later point either be 'captured' or canceled. By default, we charge the customer's card or bank account immediately when they complete the payment. If you set a capture delay however, we will delay the automatic capturing of the payment for the specified amount of time. For example 8 hours or 2 days. To schedule an automatic capture, the captureMode must be set to automatic. The maximum delay is 7 days (168 hours). Possible values: ... hours ... days	8 hours
applicationFee	JsonNullable<PaymentRequestApplicationFee>	➖	With Mollie Connect you can charge fees on payments that your app is processing on behalf of other Mollie merchants. If you use OAuth to create payments on a connected merchant's account, you can charge a fee using this applicationFee parameter. If the payment succeeds, the fee will be deducted from the merchant's balance and sent to your own account balance. If instead you want to split a payment on your own account between yourself and a connected merchant, refer to the routing parameter.
routing	List<EntityPaymentRoute>	➖	This functionality is not enabled by default. Reach out to our partner management team if you wish to use it. With Mollie Connect you can charge fees on payments that your app is processing on behalf of other Mollie merchants. If you create payments on your own account that you want to split between yourself and one or more connected merchants, you can use this routing parameter to route the payment accordingly. The routing parameter should contain an array of objects, with each object describing the destination for a specific portion of the payment. It is not necessary to indicate in the array which portion goes to yourself. After all portions of the total payment amount have been routed, the amount left will be routed to the current organization automatically. If instead you use OAuth to create payments on a connected merchant's account, refer to the applicationFee parameter.
sequenceType	Optional<SequenceType>	➖	N/A	oneoff
mandateId	JsonNullable<String>	➖	Only relevant for recurring payments and stored cards. When creating recurring or stored cards payments, the ID of a specific mandate can be supplied to indicate which of the customer's accounts should be debited.	mdt_5B8cwPMGnU
customerId	Optional<String>	➖	N/A	cst_5B8cwPMGnU
profileId	Optional<String>	➖	The identifier referring to the profile this entity belongs to. Most API credentials are linked to a single profile. In these cases the profileId can be omitted in the creation request. For organization-level credentials such as OAuth access tokens however, the profileId parameter is required.	pfl_5B8cwPMGnU
dueDate	Optional<String>	➖	The date by which the payment should be completed in YYYY-MM-DD format	2025-01-01
storeCredentials	Optional<Boolean>	➖	Whether the card details should be stored for the customer after a successful payment. This will create a mandate for the customer, allowing for future customer present saved-card CIT payments. Requires customerId, cardToken, and the creditcard method to be specified.	true
testmode	JsonNullable<Boolean>	➖	Whether to create the entity in test mode or live mode. Most API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting testmode to true.	false
applePayPaymentToken	Optional<String>	➖	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.	{"paymentData": {"version": "EC_v1", "data": "vK3BbrCbI/...."}}
company	Optional<Company>	➖	Billie is a business-to-business (B2B) payment method. It requires extra information to identify the organization that is completing the payment. It is recommended to include these parameters up front for a seamless flow. Otherwise, Billie will ask the customer to complete the missing fields during checkout.
cardToken	Optional<String>	➖	When creating credit card payments using Mollie Components, you need to provide the card token you received from the card component in this field. The token represents the customer's card information needed to complete the payment. Note: field only valid for oneoff and first payments. For recurring payments, the customerId alone is enough.	tkn_12345
voucherNumber	Optional<String>	➖	The card token you received from the card component of Mollie Components. The token represents the customer's card information needed to complete the payment.	1234567890
voucherPin	Optional<String>	➖	The PIN on the gift card. You can supply this to prefill the PIN, if the card has any.	1234
consumerDateOfBirth	LocalDate	➖	The customer's date of birth. If not provided via the API, iDeal in3 will ask the customer to provide it during the payment process.	2000-01-01
extraMerchantData	Map<String, Object>	➖	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.
sessionId	Optional<String>	➖	The unique ID you have used for the PayPal fraud library. You should include this if you use PayPal for an on-demand payment.	...
digitalGoods	Optional<Boolean>	➖	Indicate if you are about to deliver digital goods, such as for example a software license. Setting this parameter can have consequences for your PayPal Seller Protection. Refer to PayPal's documentation for more information.	true
customerReference	Optional<String>	➖	Used by paysafecard for customer identification across payments. When you generate a customer reference yourself, make sure not to put personal identifiable information or IP addresses in the customer reference directly.	1234567890
terminalId	Optional<String>	➖	The ID of the terminal device where you want to initiate the payment on.	term_1234567890