Introduction

This guide describes the API to be used with the CM Payments System.

Order vs. Payment

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.

Payment Flows

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 several samples.

Shopper Data and Order Items

For some payment methods additional data is required to be able to successfully process the payment request. For those situations the following pages are applicable Shopper Data and Order Items.

Status Notification and Considered Safe

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:

Field	Type	Description
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 https://www.myshop.com/payments/notification?order=${order_key}&country=${country}, with the parameters order_key and country, is called as https://www.myshop.com/payments/notification?order=16965E9DA949EA65A6D73E31FE0E88B3&country=NL.

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 https://www.myshop.com/payments/notification?id= becomes

https://www.myshop.com/payments/notification?id=vk20170224p

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 Payment System.

Restrictions

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.

Contact

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.