How to create payment links via Montonio's API?

New to payment links? Start with Payment Links vs. Regular Checkout Payments. To create links without coding, see How to activate and create payment links in the Partner System.

💡 Note: The payment links service has a fixed monthly fee. Transactions made through payment links are also charged based on the payment method used and its rates.

Creating payment links via API

Full technical details, code examples and request formats are in our API documentation.

When you create a payment link, the API returns two links you can share with your customer:

A full URL, for example pay.montonio.com/1088b447-a9ab-...
A short URL, which is easier to share by text message or on social media

When customers open the link, they see the amount, the payment description and the payment methods you've activated in the Partner System.

💡 Note: A payment link shows only the payment methods activated in your Montonio Partner System. Supported currencies are EUR and PLN.

Useful parameters

These parameters control how your payment link looks and works. Some are required, and others are optional. For the full list of fields, see the API documentation.

Parameter	What it does	Good to know
`locale`	Sets the language of the payment page.	Required. Options: DE, EN, ET, FI, LT, LV, PL, RU.
`expiresAt`	Sets when the link stops accepting payments.	Required. There's no maximum duration.
`askAdditionalInfo`	Asks the customer for their name and email.	Required. See "Collecting payer information" below.
`type`	Makes the link reusable or one-time.	Default is reusable. Use `one_time` for single payments.
`preferredProvider` + `preferredCountry`	Sends the customer straight to a specific bank, skipping the payment link page.	Use both together, and make sure the bank matches the country. Bank payments only.
`returnUrl`	Redirects the customer to your own page after payment.	You'll need to build your own success and error messages.
`notificationUrl`	Sends you a webhook when a payment is completed.	Allowlist our IPs to receive webhooks (see the API docs).
`paymentReference`	Adds a structured bank reference number.	Bank payments only. Leave it out if you don't use reference numbers, because payments fail if the format is wrong.
`merchantReference`	Adds your own unique ID to the link and its orders.	One-time links only.
`showShippingOptions`	Lets customers choose a carrier and pickup point.	See "Payment links with shipping" below.

Collecting payer information

Use askAdditionalInfo to decide whether customers enter their details before paying.

Set to true: The customer enters their first name, last name and email. You'll see this information on the order in the Partner System. Payment link will look like this:

Set to false: The customer goes straight to payment with no fields to fill in, which makes paying faster. Payment link will look like this:

Note: If set to false, the order won't include the payer's name or email, so you won't see this information in the Partner System.

Payment links with shipping options

You can let customers choose a delivery option directly on the payment link. They select a carrier and a pickup point, and the shipping cost is added to the total. For example, a €100 payment with €5 shipping comes to €105.

Currently, this feature only supports shipments to parcel machines.

To use shipping options:

You need active shipping methods through Montonio contracts.
Set showShippingOptions to true.
Set askAdditionalInfo to true. Customers also enter their phone number.
Add customerCountry, the country where the parcel will be delivered.

💡 Note: If your store has no active shipping methods, the payment link can't be created and you'll get a 400 error.

A shipment is created automatically when the customer pays. Here's how the payment link will look like:

How payment links behave

Each payment creates an order. An order is created in Montonio when the customer proceeds to payment.
Links are reusable by default. The same link can be paid multiple times, and each payment creates a separate order. To allow only one payment, set type to one_time.
Links expire. Every link needs an expiry date, after which it stops accepting payments.
Customers can retry. If a payment fails, the customer can try again from the payment link page.
Customers see a confirmation page. After a successful payment, they're shown Montonio's standard thank-you page, which they can save as proof of payment. If you've set a returnUrl, they're sent to your page instead.

Troubleshooting

These are the most common errors you might see when creating a payment link via API, and how to fix them.

Error	What it usually means
400	A field in the request is incorrect, or shipping options are on but your store has no active shipping methods. Check the error message for details.
401	The access key is missing or wrong, or you're using the wrong environment (sandbox vs. live).
403	The secret key is wrong, or you're using the wrong environment.