Migrating from v1 to v2¶
Why upgrade to v2?¶
The Mollie API v2 offers some compelling new features compared to the older v1
API:
- Fully supports multicurrency. You can create payments, subscriptions, and refunds in
non-
EUR
currencies. Your account will still be settled inEUR
, so new fields have been added in the API to reflect the settlement amount for various resources. - Possible to update details of payments via the new Update payment.
- Improved support for accessing large sets of objects, now uses cursor-based pagination instead of pagination based on counts and offsets.
- Settlement details are now available for refunds and chargebacks as well.
- New features such as Mollie Components, using Orders API for Pay later and Slice it, and wallets such as Apple Pay are only available in the Mollie API v2.
- Improved error messages. Error message will contain more details to help you quickly resolve any implementation problems.
Changes in v2¶
In general, the API has adopted the HAL specification, allowing you to discover new resources and follow links to new resources while working with the API.
Several fields have changed too to support new features or to clear up confusing aspects of the v1
API.
The identifier for the payment method Bancontact has been renamed from mistercash
to bancontact
in the v2
API.
Some resources support embedding of related sub-resources. For instance, when retrieving a payment any refunds can be
embedded by using the embed=refunds
query string parameter. See the
Get payment endpoint for more information.
Amount changes¶
All amounts in the API are passed as a map containing both a currency
and a value
property, for example:
1 2 3 4 5 6 | { "amount": { "currency": "EUR", "value": "10.00" } } |
This example object describes an amount of €10.00.
Note
If you specify an amount, you must specify the correct number of decimals. We strongly recommend sending
value
as a string. And even though most currencies use two decimals, some use three or none, like
JPY
.
All amounts returned in the v2
API will use this format.
Locale changes¶
Only full locales with both the language and the country code are supported, e.g. nl_NL
. Locales are always returned
as full locales.
Combined date and time fields¶
Formatting of fields such as createdAt
has been updated to be strictly compliant to ISO-8601 formatting. Example
value: 2018-03-05T12:30:10+00:00
.
Changes in the Payments API¶
The following changes have been made in regards to the status of payments:
- The statuses
paidout
,refunded
andcharged_back
have been removed. - The status
cancelled
has been renamed to canceled (US English spelling). - If you want to see if a payment has been settled to your bank account, it will contain the
settlement
key in the_links
property. - If you want to see if a payment has any refunds, the payment will have the
refunds
key in the_links
property, which will point you to the refunds resource where you can view the refund details. - If you want to see if a payment has any chargebacks, the payment will have the
chargebacks
key in the_links
property, which will point you to the chargeback resource where you can view the chargeback details.
The individual billing and shipping address parameters that can be used when creating a credit card or PayPal payment
have been replaced by address objects. Instead of passing billingAddress
, billingPostal
, billingCity
,
billingRegion
and/or billingCountry
(or the equivalent fields starting with shipping
), one should now pass a
billingAddress
(and/or shippingAddress
) object, as follows:
1 2 3 4 5 6 7 8 9 10 11 | { "amount": {"currency": "USD", "value": "100.00"}, "description": "Order #12345", "billingAddress": { "streetAndNumber": "Dorpstraat 1", "postalCode": "1122 AA", "city": "Amsterdam", "region": "Noord-Holland", "country": "NL", } } |
Note
The usage of the address object parameters remains optional. Refer to the Create payment documentation for exact specifications on what input is accepted.
The following fields have been changed, renamed or moved:
cancelledDatetime
has been renamed tocanceledAt
.createdDatetime
has been renamed tocreatedAt
.expiredDatetime
has been renamed toexpiredAt
.failedDatetime
has been renamed tofailedAt
.paidDatetime
has been renamed topaidAt
.canBeCancelled
has been renamed toisCancelable
.recurringType
has been renamed tosequenceType
. This field is now always present. A one-off payment (not the start of a recurring sequence and not a recurring payment) will have the valueoneoff
.redirectUrl
andwebhookUrl
are now part of the top-level object for Payments.links.paymentUrl
has been renamed to_links.checkout
as per HAL specifications.failureReason
has been moved from the Payment resource to the credit card detail object, and no longer available for Bancontact payments.
The following fields have been removed:
expiryPeriod
has been removed from the Payment resource. You can useexpiresAt
which contains the same information.issuer
has been removed from the Payment resource. You can however, still pass it to the Create payment endpoint.details.bitcoinRate
has been removed from the Bitcoin detail object.details.bitcoinAmount
has been removed from the Bitcoin detail object.details.cardCountry
has been removed from the credit card detail object.- The option to include the settlement using the
include
query string parameter has been removed.
These new fields have been added:
settlementAmount
has been added to the responses of the Payments API, the Refunds API and the Chargebacks API. This optional field will contain the amount that will be settled to your account, converted to the currency your account is settled in. It follows the same syntax as theamount
property.Note that for refunds and chargebacks, the
value
key ofsettlementAmount
will be negative.Any amounts not settled by Mollie will not be reflected in this amount, e.g. PayPal or gift cards.
_links.status
has been added to the responses forbanktransfer
payments. Your customer can check the status of their transfer at this URL._links.payOnline
has been added to the responses forbanktransfer
payments. At this URL your customer can finish the payment using an alternative payment method also activated on your website profile.
Changes in the Refunds API¶
The following fields have been changed, renamed or moved:
amount
is now mandatory when creating a refund. You must specify bothamount.currency
andamount.value
.- The
amount
field is now of theamount
type and contains avalue
and acurrency
. payment
, which contained the payment resource related to the refund, is no longer returned. Instead, the payment ID is returned by default, in thepaymentId
field. The payment resource can still easily be accessed using thepayment
key in the_links
property.- The resource will contain a link to the settlement if it is settled (via the
settlement
key in the_links
property.
These new fields have been added:
settlementAmount
has been added. See the explanation of the settlementAmount for the Payments API.
Changes in the Chargebacks API¶
The following fields have been changed, renamed or moved:
- The
amount
field is now of theamount
type and contains avalue
and acurrency
. chargebackDatetime
has been renamed tocreatedAt
.reversedDatetime
has been renamed toreversedAt
. This field is now only returned if the chargeback is reversed.payment
, which contained the payment ID related to the chargeback, has been renamed topaymentId
. The payment resource can easily be accessed using thepayment
key in the_links
property.- The resource will contain a link to the settlement if it is settled (via the
settlement
key in the_links
property.
These new fields have been added:
settlementAmount
has been added. See the explanation of the settlementAmount for the Payments API.
Changes in the Methods API¶
The following fields have been changed, renamed or moved:
amount
includingminimum
andmaximum
have been renamed tominimumAmount
andmaximumAmount
. This should be an object containingvalue
andcurrency
.- The
image
fieldsnormal
andbigger
have been renamed tosize1x
andsize2x
. - Pagination has been removed, so all fields related to pagination are not available anymore. The list method will now return all payment methods.
The following parameters have been changed or added:
- The parameter
recurringType
has been renamed tosequenceType
. Possible values areoneoff
,first
orrecurring
. - The parameter
amount
has been added. This should be an object containingvalue
andcurrency
. Only payment methods that support the amount/currency will be returned. Example:https://api.mollie.com/v2/methods?amount[value]=100.00&amount[currency]=USD
Changes in the Issuers API¶
The issuers API has been removed. Instead, you can get the issuers via the
Get method endpoint on the Methods API using the issuers
include.
Changes in the Customers API¶
The following fields have been changed, renamed or moved:
createdDatetime
has been renamed tocreatedAt
.recentlyUsedMethods
has been removed.
Changes in the Subscriptions API¶
The following changes have been made in regards to the status of subscriptions:
- Subscriptions that are canceled can be retrieved from the API, and will not return a HTTP status
410 Gone
. - The
canceled
status is changed from British English to American English.
The following fields have been changed, renamed or moved:
createdDatetime
has been renamed tocreatedAt
.cancelledDatetime
has been renamed tocanceledAt
, and is now only returned when the subscription is canceled.webhookUrl
is now part of the top-level object for Subscriptions.
Changes in the Profiles API¶
The following fields have been changed, renamed or removed:
createdDatetime
has been renamed tocreatedAt
updatedDatetime
has been removed.phone
is now formatted in E.164 formatting.- The API keys subresource has been removed.
New APIs have been added, such as the Get current profile endpoint.
Changes in the Settlements API¶
The following fields have been changed, renamed or moved:
createdDatetime
has been renamed tocreatedAt
.settledDatetime
has been renamed tosettledAt
.- The fields
paymentIds
,refundIds
andchargebackIds
has been removed. - All amounts have been changed to the amount type. Note that the
costs.amount*
fields can have more decimals than you would expect. The same goes forrate.fixed
, which can contain fractional cents. amount.net
,amount.vat
andamount.gross
have been moved one level up asamountNet
,amountVat
andamountGross
.- If the settlement has been invoiced, it will contain the
invoice
key in the_links
property. - The
reference
parameter in the List settlements endpoint has been removed.
Changes in the Mandates API¶
The following fields have been changed, renamed or moved:
createdDatetime
has been renamed tocreatedAt
.
Changes in the Organizations API¶
- The fields
country
,registrationDate
andregistrationType
have been removed. - The field
address
is now an Address object.
Changes in the Permissions API¶
- The field
warning
has been removed.
Changes in the Invoice API¶
issuedDate
has been renamed toissuedAt
.paidDate
has been renamed topaidAt
.dueDate
has been renamed todueAt
.amount.net
,amount.vat
andamount.gross
have been moved one level up asnetAmount
,vatAmount
andgrossAmount
.pdf
has been moved into the_links
property.
Changes in error reporting¶
In general, error reporting has been improved to help you resolve any implementation errors as fast as possible.
The HAL specification has been adopted for error reporting as well. The difference between v1
and v2
is best
explained using an example.
The new error reporting format in v2
is the following:
1 2 3 4 5 6 7 8 9 10 11 | { "status": 401, "title": "Unauthorized Request", "detail": "Missing authentication, or failed to authenticate", "_links": { "documentation": { "href": "https://docs.mollie.com/overview/authentication", "type": "text/html" } } } |
The HTTP status returned is now part of the error response, title
is the default HTTP status message, the
message
field is renamed to detail
.