{

Introduction

This API is used for 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.

  • 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 payment, typically using Giftcards. Each payment has an unique Payment ID (PID).

Thus, an order can have multiple payments.

Payment Flow

The following diagram shows the payment flow using the menu.

Payment Flow via Menu

Steps:

  1. The shopper has finished shopping and continues to check out to pay for the order.

  2. The merchant first creates an order supplying an amount and an order reference among other parameters. The Payment System returns a unique order key and the url to the menu. The url contains all the references to identify the order to be payed.

  3. The shopper is redirected to the payment menu.

  4. After selecting a payment method and entering the payment details, the payment system authorizes the payment. Depending on the payment method the shopper can optionally be redirected to an acquirer for authentication.

  5. If the order is fully authorized the shopper is redirected back to the Merchant's web shop. Otherwise he can attempts another payment, or cancel and return to the web shop without paying.

  6. By means of an asynchronous Status Change Notification the Payment System notifies the merchant when the status of an order including any payments has been updated.

  7. The merchant checks the status of the order (and whether the order is considered safe) using the order key as provided in the response of the create request.

  8. The shopper returns to Merchant's web shop. The landing page of the web shop can be used to display a confirmation of the order to the shopper.

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) is changed. This change might or might not be relevant for the merchant.

The only parameter that the notification contains is the order reference supplied in the create order, which is appended to the Update Url configured in the account, for example:

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

To determine the status of the order, and whether or not 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 this happens directly when the payment is authorized, but it could also be daily when the payment is captured, or even longer until the actual money is received by the Payment System.