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 payments, typically using Giftcards. Each payment has a unique payment identifier.

Thus, an order can have multiple payments.

Payment Flows

Payment Flow Via Menu

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 paid.

  3. The shopper is redirected to the payment menu.

  4. The Shopper selects a payment method from menu and enter the payment details and submits request to PS for processing.

  5. The Payment System authorizes the payment. Depending on the payment method the shopper can optionally be redirected to an acquirer for authentication.

  6. If the order is fully authorized the shopper is redirected back to the Merchant's webshop. Otherwise he can attempt another payment, or cancel and return to the webshop without paying.

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

  8. 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.

  9. Payment System sends back the Status response with Confidence level (considered safe) which helps merchant decide whether or not to ship the products.

  10. The shopper returns to Merchant's webshop.

  11. The landing page of the webshop can be used to display a confirmation of the order to the shopper.

Payment Flow Via Webdirect without Redirect to Issuer

The following diagram shows the payment flow via Webdirect without Issuer redirect.

Payment Flow Via Webdirect Without Redirect To Issuer

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 paid.The menu URL can be ignored.

  3. Using the unique digital key as provided in the response of the CREATE request, the merchant then initiates the creation of a (Payment) Order using the START request.

  4. The Payment System authorizes the payment depending on the provided details.

  5. Payment System will return the status of the payment.

  6. By means of an asynchronous Status Update call Payment System notifies the merchant when the status of an Order has been updated.

  7. The merchant checks the status of the order (and whether the payment has been authorized successfully) using the order key as provided in the response of the CREATE request.

  8. Payment System sends back the Status response with Confidence level (considered safe) which helps merchant decide whether or not to ship the products.

  9. Merchant confirms to shopper that order is being processed.

Payment Flow Via Webdirect with Redirect to Issuer

The following diagram shows the payment flow via Webdirect with redirect to Issuer.

Payment Flow Via Webdirect With Redirect To Issuer

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 paid.The menu url can be ignored.

  3. Using the unique digital key as provided in the response of the CREATE request the merchant then initiates the creation of a (Payment) Order using the START request.

  4. The Payment System authorizes the payment depending on the provided details.

  5. Payment System returns the status of the payment and redirect information.

  6. Merchant sends the redirect information to Shopper.

  7. Shopper is redirected to his/her Issuing bank for Authorizing payment.

  8. Payment System receives Authorization Response from Issuing bank.

  9. Payment System will process the Authorization Response.

  10. By means of an asynchronous Status Update call Payment System notifies the merchant when the status of an Order has been updated.

  11. The merchant checks the status of the order (and whether the payment has been authorized successfully) using the order key as provided in the response of the CREATE request.

  12. Payment System sends back the Status response with Confidence level (considered safe) which helps merchant decide whether or not to ship the products.

  13. Merchant confirms to shopper that order is being processed.

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 only parameter that the notification contains is the order reference supplied in the create-request, 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 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.

Shopper

The Payment System provides a functionality through which a shopper can organise the billing address including name of the shopper, independent of orders. The provided key can be used in the order API to create an Order request. The primary reason is to support additional payment methods, e.g. SEPA_DIRECT_DEBIT and PAYPAL.

Payment Flow via Menu with Shopper

Steps:

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

  2. The shopper creates shopper details (Name and Address) using the resource provided by the merchant.
    The Payment System returns a unique shopper key and address key.

  3. The merchant then creates an order using the address key obtained from above step by 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 paid.

  4. The shopper is redirected to the payment menu.

The further steps are similar to the payment flow as shown in the previous diagram of "Payment Flow Via Menu".