Sign in

v55

latestOpenAPI 3.1.0CC-BY-NC-SA-4.0raw.githubusercontent.com2026-08-011243791.8 MB
Customers API

Create customer payment

Creates a payment for the customer.

Linking customers to payments enables you to:

  • Keep track of payment preferences for your customers
  • Allow your customers to charge a previously used credit card with a single click in our hosted checkout
  • Improve payment insights in the Mollie dashboard
  • Use recurring payments

This endpoint is effectively an alias of the Create payment endpoint with the customerId parameter predefined.

post/v2/customers/{customerId}/payments

Headers

idempotency-keystring
Example:123e4567-e89b-12d3-a456-426

A unique key to ensure idempotent requests. This key should be a UUID v4 string.

Request body

resourcestring

Indicates the response contains a payment object. Will always contain the string payment for this endpoint.

idstring
mode'live' | 'test'

Whether this entity was created in live mode or in test mode.

descriptionstring required

The description of the payment 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.

redirectUrlstring nullable required

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.

cancelUrlstring nullable

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.

webhookUrlstring nullable

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'ca_ES' | 'cs_CZ' | 'da_DK' | 'de_AT' | 'de_CH' | 'de_DE' | 'de_LU' | 'en_GB' | 'en_US' | 'es_ES' | 'fi_FI' | 'fr_BE' | 'fr_FR' | 'fr_LU' | 'hu_HU' | 'is_IS' | 'it_IT' | 'lt_LT' | 'lv_LV' | 'nb_NO' | 'nl_BE' | 'nl_NL' | 'pl_PL' | 'pt_PT' | 'sk_SK' | 'sv_SE' | 'null' nullable

Sets the language for customer-facing content and communications.

countryCodestring nullable

This optional field contains your customer's ISO 3166-1 alpha-2 country code, detected by us during checkout. This field is omitted if the country code was not detected.

issuerstring nullable

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

restrictPaymentMethodsToCountrystring nullable

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.

captureMode'automatic' | 'manual' nullable

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.

captureDelaystring nullable

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

captureBeforestring nullable

Indicates the date before which the payment needs to be captured, in ISO 8601 format. From this date onwards we can no longer guarantee a successful capture. The parameter is omitted if the payment is not authorized (yet).

sequenceType'oneoff' | 'first' | 'recurring'
subscriptionIdstring
mandateIdstring
customerIdstring
profileIdstring

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.

settlementIdstring
orderIdstring
status'open' | 'pending' | 'authorized' | 'paid' | 'canceled' | 'expired' | 'failed'

The payment's status. Refer to the documentation regarding statuses for more info about which statuses occur at what point.

isCancelableboolean nullable

Whether the payment can be canceled. This parameter is omitted if the payment reaches a final state.

createdAtstring

The entity's date and time of creation, in ISO 8601 format.

authorizedAtstring nullable

The date and time the payment became authorized, in ISO 8601 format. This parameter is omitted if the payment is not authorized (yet).

paidAtstring nullable

The date and time the payment became paid, in ISO 8601 format. This parameter is omitted if the payment is not completed (yet).

canceledAtstring nullable

The date and time the payment was canceled, in ISO 8601 format. This parameter is omitted if the payment is not canceled (yet).

expiresAtstring nullable

The date and time the payment will expire, in ISO 8601 format. This parameter is omitted if the payment can no longer expire.

expiredAtstring nullable

The date and time the payment was expired, in ISO 8601 format. This parameter is omitted if the payment did not expire (yet).

failedAtstring nullable

The date and time the payment failed, in ISO 8601 format. This parameter is omitted if the payment did not fail (yet).

dueDatestring

The date the bank transfer payment should expire, in YYYY-MM-DD format. 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.

<Callout icon="📘" theme="info"> If `dueDate` falls out of business days, it will be set to the **next business day** and the payment will expire at 00:00 (on the following business day). Example: `dueDate` is `2025-12-06` (Saturday) -> `dueDate` will be set for `2025-12-08`, `expiresAt` `2025-12-09 00:00` </Callout>
storeCredentialsboolean

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.

testmodeboolean nullable

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.

applePayPaymentTokenstring

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. For example: {"paymentData": {"version": "EC_v1", "data": "vK3BbrCbI/...."}}

cardTokenstring

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.

googlePayPaymentTokenstring

The Google Pay payment token object (encoded as JSON) returned by the Google Pay SDK after the customer authorizes the payment. The token contains the payment information needed to complete the payment.

The object should be passed encoded in a JSON string.

voucherNumberstring

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.

voucherPinstring

The PIN on the gift card. You can supply this to prefill the PIN, if the card has any.

consumerDateOfBirthstring date

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.

extraMerchantDataobject

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 <Anchor label="Klarna Developer Documentation" target="_blank" href="https://docs.klarna.com/acquirer/mollie/api/extra-merchant-data/">Klarna Developer Documentation</Anchor>.

Reach out to your account manager at Mollie to enable this feature with Klarna, and to agree on which fields you can send.

sessionIdstring

The unique ID you have used for the PayPal fraud library. You should include this if you use PayPal for an on-demand payment.

digitalGoodsboolean

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.

customerReferencestring

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.

If not provided, Mollie will use a hashed version of the customer's IP address.

terminalIdstring

The ID of the terminal device where you want to initiate the payment on. See also the Terminals API.

Example request

{
  "resource": "payment",
  "id": "tr_5B8cwPMGnU",
  "mode": "live",
  "description": "Chess Board",
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountRefunded": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountRemaining": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountCaptured": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountChargedBack": {
    "currency": "EUR",
    "value": "10.00"
  },
  "redirectUrl": "https://example.org/redirect",
  "cancelUrl": "https://example.org/cancel",
  "webhookUrl": "https://example.org/webhooks",
  "lines": [
    {
      "type": "physical",
      "description": "LEGO 4440 Forest Police Station",
      "quantity": 1,
      "quantityUnit": "pcs",
      "unitPrice": {
        "currency": "EUR",
        "value": "10.00"
      },
      "discountAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "totalAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "vatRate": "21.00",
      "vatAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "sku": "9780241661628",
      "categories": [
        "meal",
        "eco"
      ],
      "imageUrl": "https://...",
      "productUrl": "https://...",
      "recurring": {
        "description": "Gym subscription",
        "interval": "12 months",
        "amount": {
          "currency": "EUR",
          "value": "10.00"
        },
        "times": 1,
        "startDate": "2024-12-12"
      }
    }
  ],
  "billingAddress": {
    "title": "Mr.",
    "givenName": "Piet",
    "familyName": "Mondriaan",
    "organizationName": "Mollie B.V.",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "Apt. 1",
    "postalCode": "1234AB",
    "email": "piet@example.org",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL"
  },
  "shippingAddress": {
    "title": "Mr.",
    "givenName": "Piet",
    "familyName": "Mondriaan",
    "organizationName": "Mollie B.V.",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "Apt. 1",
    "postalCode": "1234AB",
    "email": "piet@example.org",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL"
  },
  "locale": "en_US",
  "countryCode": "BE",
  "method": "ideal",
  "issuer": "ideal_INGBNL2A",
  "restrictPaymentMethodsToCountry": "NL",
  "captureMode": "manual",
  "captureDelay": "8 hours",
  "captureBefore": "2024-03-20T09:28:37+00:00",
  "applicationFee": {
    "amount": {
      "currency": "EUR",
      "value": "10.00"
    }
  },
  "routing": [
    {
      "resource": "route",
      "id": "rt_5B8cwPMGnU",
      "mode": "live",
      "amount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "destination": {
        "type": "organization",
        "organizationId": "org_1234567"
      },
      "createdAt": "2024-12-12T10:00:00+00:00",
      "releaseDate": "2024-12-12",
      "_links": {
        "self": {
          "href": "https://...",
          "type": "application/hal+json"
        },
        "payment": {
          "href": "https://...",
          "type": "application/hal+json"
        }
      }
    }
  ],
  "sequenceType": "oneoff",
  "subscriptionId": "sub_5B8cwPMGnU",
  "mandateId": "mdt_5B8cwPMGnU",
  "customerId": "cst_5B8cwPMGnU",
  "profileId": "pfl_5B8cwPMGnU",
  "settlementId": "stl_5B8cwPMGnU",
  "orderId": "ord_5B8cwPMGnU",
  "status": "open",
  "statusReason": {
    "code": "insufficient_funds",
    "message": "The account associated with the card has insufficient funds. The shopper should use another payment method or\ncontact their bank."
  },
  "isCancelable": true,
  "details": {
    "consumerName": "John Doe",
    "consumerAccount": "NL91ABNA0417164300",
    "consumerBic": "ABNANL2A",
    "cardNumber": "************1234",
    "bankName": "Mollie Bank",
    "bankAccount": "NL91ABNA0417164300",
    "bankBic": "ABNANL2A",
    "transferReference": "...",
    "bizumReference": "2901tq2ure1d",
    "cardFingerprint": "...",
    "cardHolder": "John Doe",
    "cardAudience": "consumer",
    "cardLabel": "Mastercard",
    "cardCountryCode": "NL",
    "cardExpiryDate": "12/25",
    "cardFunding": "credit",
    "cardSecurity": "normal",
    "feeRegion": "maestro",
    "cardMaskedNumber": "...",
    "card3dsEci": "...",
    "cardBin": "...",
    "cardIssuer": "...",
    "failureReason": "card_declined",
    "failureMessage": "Your card was declined.",
    "wallet": "applepay",
    "paypalReference": "...",
    "paypalPayerId": "...",
    "sellerProtection": "ELIGIBLE",
    "paypalFee": {
      "currency": "EUR",
      "value": "10.00"
    },
    "customerReference": "...",
    "terminalId": "term_12345",
    "maskedNumber": "...",
    "receipt": {
      "authorizationCode": "...",
      "applicationIdentifier": "...",
      "cardReadMethod": "contactless",
      "cardVerificationMethod": "no-cvm-required"
    },
    "creditorIdentifier": "...",
    "dueDate": "2025-01-01",
    "signatureDate": "2024-03-20",
    "bankReasonCode": "...",
    "bankReason": "...",
    "endToEndIdentifier": "...",
    "mandateReference": "...",
    "batchReference": "...",
    "fileReference": "...",
    "qrCode": {
      "height": 300,
      "width": 300,
      "src": "https://www.mollie.com/images/qr-code.png"
    },
    "voucherNumber": "...",
    "issuer": "...",
    "remainderAmount": {
      "currency": "EUR",
      "value": "10.00"
    },
    "remainderMethod": "creditcard"
  },
  "createdAt": "2024-03-20T09:13:37+00:00",
  "authorizedAt": "2024-03-20T09:28:37+00:00",
  "paidAt": "2024-03-20T09:28:37+00:00",
  "canceledAt": "2024-03-20T09:28:37+00:00",
  "expiresAt": "2024-03-20T09:28:37+00:00",
  "expiredAt": "2024-03-20T09:28:37+00:00",
  "failedAt": "2024-03-20T09:28:37+00:00",
  "dueDate": "2025-12-08",
  "storeCredentials": true,
  "_links": {
    "self": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "checkout": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "mobileAppCheckout": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "changePaymentState": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "dashboard": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "refunds": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "chargebacks": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "captures": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "settlement": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "customer": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "mandate": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "subscription": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "order": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "terminal": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "documentation": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "status": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "payOnline": {
      "href": "https://...",
      "type": "application/hal+json"
    }
  },
  "applePayPaymentToken": "{\"paymentData\": {\"version\": \"EC_v1\", \"data\": \"vK3BbrCbI/....\"}}",
  "company": {
    "registrationNumber": "12345678",
    "vatNumber": "NL123456789B01",
    "entityType": "LLC"
  },
  "cardToken": "tkn_12345",
  "googlePayPaymentToken": "{\"signature\": \"MEYCIQCv...\", \"protocolVersion\": \"ECv2\", \"signedMessage\": \"{\\\"encryptedMessage\\\":\\\"...\\\",\\\"ephemeralPublicKey\\\":\\\"...\\\",\\\"tag\\\":\\\"...\\\"}\"}",
  "voucherNumber": "1234567890",
  "voucherPin": "1234",
  "consumerDateOfBirth": "2000-01-01",
  "sessionId": "...",
  "digitalGoods": true,
  "customerReference": "1234567890",
  "terminalId": "term_1234567890"
}

Response

The newly created payment object.