Migrating from Payments API to the Orders API

If you want to start using the Orders API, you can use this guide to migrate from the v2 Payments API to the Orders API. Note that the Payments API is not going to be replaced by the Orders API.

Prerequisites

This guide assumes you are migrating from the v2 Payments API. If you are migrating from the v1 API please first review the v2 migration guide to learn about the differences between the v1 and the v2 API.

Differences and similarities

To create a payment in the orders API the Create order API needs to be used.

The Create payment and Create order APIs are very similar. Both support the following parameters: amount, redirectUrl, webhookUrl, locale, method and metadata. For orders, locale is a required parameter.

For orders, there is no description field. The Payment description will be automatically created by Mollie and will contain the order number, your profile’s name and your profile’s website.

If you specify a payment method using the method API parameter the payment parameter can be used to supply additional payment parameters. For example the iDEAL issuer can be specified using the following JSON body payload:

1
2
3
4
5
6
7
{
    "orderNumber": "1337",
    "method": "ideal",
    "payment": {
        "issuer": "ideal_INGBNL2A"
    }
}

Additional parameters are required to be able to create an order: orderNumber, lines and billingAddress. The lines parameter should be an array of order lines describing the actual order contents. The billingAddress should contain the address of the person who will be billed for the order amount.

  Payments API Orders API
amount Identical between Payments API and Orders API.
redirectUrl Identical between Payments API and Orders API.
webhookUrl See Payment status changes. Orders have two flows: authorized and paid. See Order status changes.
locale Recommended in Payments API. Required for Orders API.
method Does not support pay after delivery payment methods. Supports Klarna Pay later and Klarna Slice it.
metadata Identical between Payments API and Orders API.
description Required for Payments API. Not available.
orderNumber Not available. Required for Orders API.
lines Not available. Specify the products sold in the order.
billingAddress Optional for Payments API. Required for Orders API. Has several new fields.

When the order is created the response will contain a checkout URL just like in the payments API:

1
2
3
4
5
6
7
8
 {
     "_links": {
         "checkout": {
             "href": "https://www.mollie.com/payscreen/order/checkout/pbjz8x",
             "type": "text/html"
         }
     }
 }

Your customer should be redirected to this URL to complete the order payment. This is the same as in the Payments API.

The only difference occurs when the customer chooses a payment method that requires authorization. This is the case with pay later payment methods. The customer will have to authorize the payment, and the payment is not executed immediately. When a shipment is created for an authorized order a capture is made to process the payment. For more info on the authorize payment flow please see Order status changes for details on the orders’ statuses.

Note that the checkout link has a longer expiry period than a payment checkout URL. The exact expiry time can be retrieved from the expiresAt property in the API response.

Retrieving payment methods

The retrieval of a list of payment methods for orders is slightly different from the Payments API. You will need to supply a resource parameter with value orders, and a billingCountry parameter. This last parameter is used to check whether your customer is eligible for certain payment methods, such as Klarna Slice it.

Example: https://api.mollie.com/v2/methods?resource=orders&billingCountry=DE

Receiving status updates

Just like in the payments API you can specify a webhookUrl that will be used by Mollie to inform your back office when the status of an order has changed. You can then use the Mollie API to retrieve the order status.

Shipping

When an order payment is successfully completed by the customer the payment status can be either paid or authorized.

Pay later payment methods will have an authorized status. Shipping is required and it ensures you will be settled. Note that the customer will receive an invoice per shipment.

Shipping can be done using the Create Shipment API or directly from the Mollie Dashboard.

If needed, you can create multiple shipments per order. In the shipment you specify the order lines that are to be shipped.

When all order lines are either shipped or canceled the order is completed.

Refunding

Refunding works almost the same as in the payments API. You will have to use the Create order refund API and specify which order lines are to be refunded. If no lines are specified the whole order will be refunded.