Migrating from Orders to Payments
It is no longer recommended to use the Orders API. Instead, you should integrate with the Payments API which is simpler and more flexible. If you already have an integration with the Orders API you may want to migrate to the Payments API to get access to new features. Follow this guide to understand the changes between the Orders API and Payments API.
Creating a payment
Update your code in your checkout and change the create order endpoint to the create payment endpoint. There are a differences in properties you can provide.
- Instead of
orderNumber
set thedescription
. - The field
lines.name
is not available for Payments. Uselines.description
instead. - The field
consumerDateOfBirth
is not available for Payments. - The field
expiresAt
on the Payments API cannot be used to set the authorization expiration.
While not required for every payment method, it is recommended to add
lines
,billingAddress
, andlocale
for all payments. This will improve the checkout experience for your customer and can also prevent chargebacks and fraud.
With the Orders API, orders with the method klarna
, billie
or riverty
would have an authorized
status. With the Payments API, a payment will be captured immediately -if supported by the payment method- and result in a paid
payment.
If you want to have the same behaviour where you authorize first so you can capture later, you can set the captureMode
to manual
. This will result in a payment with a status of authorized
. For more information, see the place a hold for a payment guide.
If you do not fulfil your orders within 24 hours, it is strongly recommended to authorize and capture separately. By shortening the time between collecting the funds and your customer receiving their order, you reduce the risk for chargebacks.
Updating Orders and Payments
Where the Orders API allowed for updating the lines
and changing the authorized amount, the Payments API does not support this. Once a payment is created, the amount
and lines
cannot be updated.
Shipments and Captures
With the Shipments API an Order could be marked as completed
. For Orders in an authorized
state it would also automatically capture the funds. It is not possible to create shipments for Payments.
For payments that are in an authorized
state, the Captures API can be used the capture the authorized funds. See capturing the authorized funds for more information.
There are a few differences between the Shipments API and the Captures API:
- The Captures API can only be used for payments that are in the
authorized
state. - Captures are based on
amount
instead of an array oflines
. - You cannot provide a
tracking
object. - Captures have a
status
and are asynchronous. You will receive a webhook when the status changes.
Capture the funds when you have fulfilled the order, the same way as you would with the Shipments API.
You cannot use the Captures API to capture funds of an Order or of a Payment that is part of an Order. Either use the Shipments API or ship the order manually via Mollie Dashboard.
Canceling and releasing authorization
The Orders API allowed for canceling line items or the entire order. For Orders in an authorized
state, this would result in the release of the authorized funds. Payments cannot be canceled if they are in a final state like paid
.
For payments that are in an auhorized
state, the release payment authorization endpoint can be used to release the authorized funds. See release an authorization for more information.
It is not possible to provide a specific amount to release from an authorization. The full remaining authorized amount will be released.
Refunds
For Orders there were two ways to refund:
- Refund the Order by providing
lines
with the create order refund endpoint. - Refund the related Payment by providing an
amount
with the create payment refund endpoint.
If your integrations uses the create order refund endpoint you should update your code to use the create payment refund endpoint instead.
For Orders you can use the same create payment refund endpoint to handle refunds by using the
id
of the Payment.
Updating references
If you store a reference to the Mollie Order ID (e.g. ord_pbjz8x
) in your database, you may want to update this to the corresponding Payment ID (e.g. tr_hf8UjsS26d
). This will allow you to no longer call any Orders API endpoint for retrieving a payment or triggering a refund.
If there was no
webhookUrl
provided for the Payment when the Order was created, you will not receive a webhook with a Payment ID. Instead, you will receive a webhook with the Order ID.
Every Order will have one or more Payments linked to it. You can retrieve these via the List Orders or Get Order endpoints by including the embed=payments
query parameter. In most cases, there will be a single Payment. If there are multiple, identify the Payment that corresponds with the status of the Order. For example, if the Order is completed
or paid
, locate the Payment that is paid
.
Make sure that no Order is in the state
authorized
as it is not possible to capture the funds via the Captures API for a Payment that is part of an Order.
Updated about 5 hours ago