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 the description.
• The field lines.name is not available for Payments. Use lines.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, and locale 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 of lines.
• 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:

1. Refund the Order by providing lines with the create order refund endpoint.
2. 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.