Online Payments

API Reference for Online Payments

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:

FieldTypeDescription
countryCountryThe (billing) country of the shopper as ISO 3166-1 Alpha 2.
currencyCurrencyThe order currency as ISO 4217 Alpha 3, e.g. "EUR".
client_idString(1, 50)The id of the shopper.
order_keyOrderKeyThe generated order key.
languageLanguageThe language of the shopper as ISO 639-1 Alpha 2.
merchant_nameString(1, 50)The name of the merchant.
order_referenceString(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.


Did this page help you?