This guide describes the API to be used with the CM Payments System.
The Payment System makes a distinction between Orders and Payments.
An order is an instruction for a specific amount to be paid by a shopper and can obtain shopping basket items.
A payment is an attempt to pay an order by a shopper. This attempt is not necessarily successful, in which case the shopper
can try again to pay the order. Furthermore, the shopper can pay the order with multiple partial payments, typically using
gift cards. Therefore, an order can have multiple payments.
In addition, each order and each payment have their own unique identifier. These identifiers are used throughout the various
API calls, but are also helpful when communicating with support.
There are several possibilities on how to interact with the Payment System. Below are the most common flows for interactions
between shopper, merchant, issuer, and the Payment System. See the section Common Payment Flows for
The merchant is notified of a change in the status of the order (including any payment) by an
asynchronous call to an Update Url that is configured in his account. This Update Url does not
contain any status information of the order or payment(s). It only notifies that the status of
order or payment(s) has changed. This change might or might not be relevant for the merchant.
The Update Url can be parameterized by including one or multiple placeholders:
|country||Country||The (billing) country of the shopper as ISO 3166-1 Alpha 2.|
|currency||Currency||The order currency as ISO 4217 Alpha 3, e.g. "EUR".|
|client_id||String(1, 50)||The id of the shopper.|
|order_key||OrderKey||The generated order key.|
|language||Language||The language of the shopper as ISO 639-1 Alpha 2.|
|merchant_name||String(1, 50)||The name of the merchant.|
|order_reference||String(1, 255)||The order reference from the merchant.|
For example the Update Url
with the parameters
country, is called as
If the Update Url ends with an equal sign ('=') or a forward slash ('/'), then the order reference, as supplied in the
create order request, is appended to the Url. For example the Url
To determine the status of the order, and if the order can be shipped, get the details of
the order. If the response contains the element
considered_safe it is safe to ship the order.
Considered Safe does not only consider the status of the payments, but also the payment methods used.
Depending on the payment method, an order can be set directly to safe after authorization, but it can
also be delayed when the payment is captured, or even longer until the actual money is received by the
- The Update Url works only for ports 80 (http) and 443 (https), due to security constraints on the Payments platform. This
restriction applies to both the production and sandbox environments.
- Any unknown or unmatched placeholder is replaced by a blank value, such that the resulting Url is still valid.
If you have questions about the API, or need specific payment methods in your test account,
contact us at [email protected]
You can sign up for a test account here.
Updated about 5 hours ago