NAV Navbar

Introduction

Welcome to the Ceevo API. This API can be used to accept almost any type of payment.

Getting Started

This guide shows you how to start accepting online payments with Ceevo and is in three sections; plugins, payment widget, and RESTful API. Use the links below to navigate to each respective section.

Authentication

Ceevo uses a mix of authentication mechanisms to verify your API requests with your account’s API key or Client Credentials. If you do not include authentication key when making an API request, or use one that is incorrect or outdated, Ceevo returns an error.

Each account has two separate authentication keys; one for testing, and one for live transactions. All API requests exist in either test or live modes. These modes are separate from each other, meaning objects in one mode cannot be manipulated in the other.

Two types of authentication keys: APIKey and Client Credentials.

API requests must include an APIKey in a header, see example below:

X-CV-APIKey: xxxxxx-xxxx-xxxx-xxxx

Client Credentials should not be sent in API requests as only access token is required. To authenticate an API call, access token must be included in the HTTP header.

Access token can be obtained from the Ceevo authorisation server, see example below:


 POST /auth/realms/ceevo-realm/protocol/openid-connect/token HTTP/1.1
 Host: auth.ceevo.com

 grant_type=client_credentials
 &client_id=xxxxxxxxxx
 &client_secret=xxxxxxxxxx

Once authentication is successful, access token, token expiry, and other OAuth2 data will be available in the API response body. This access token must be included in the HTTP header of all subsequence API calls, see example below:

Authorization: Bearer access_token

Each account has a total of four authentication keys: APIKey (live mode), APIKey (test mode), Client Credential (live mode), and Client Credential (test mode).

Authentication keys can be found under "Integration" in the Ceevo Dashboard (Dashboard > Integration).

Payment Methods

Ceevo supports most payment methods. These include credit/debit cards (Mastercard/Visa) and popular alternative payment methods (APMs), such as Ideal and Sofort.

Supported payment methods can be found under "Payment Methods" in your account (Dashboard > Settings > Payment settings).

Payment Essential

Online payment can be segmented into two distinct categories:

Customer-Initiated Transactions (CIT)

A customer who places an order at an online store and confirms payment; this is an example of a typical Customer-Initiated Transactions (CIT).

In the CIT scenario, a customer is actively involved in the payment process. For such transactions, it is recommended to authenticate the customer with the payment scheme. This is to minimize risk and to stay compliant with the regulatory requirement (i.e. Strong Customer Authentication - SCA / PSD2).

Merchant-Initiated Transactions (MIT)

Certain business models charge customers after services are rendered, or take bill customers on a subscription basis; these are examples of Merchant-Initiated Transactions (MIT).

In the MIT scenario, the customer is absent from the payment process, with the transaction utilising stored customer payment details. Securing customer payment data is becoming more and more challenge and requires frequent operation to keep customer payment data up-to-date.

Payment Widget SDK

Overview

The Payment Widget SDK is our JavaScript library for collecting sensitive payment information directly from your customers.

Customer payment details collected using the Payment Widget SDK, such as card or bank account information, can be tokenised. This information can be stored in a customer object for later use via the charge API.

Customer payment details are converted into an account token. These details are appended to the payment form once the customer confirms their action at checkout.

Because all sensitive information is handled by the Payment Widget SDK, it features simple PCI compliance with SAQ A reporting.

The Payment Widget SDK is designed to be embedded into your payment form. Integration of the payment widget is as follows:

Setup

Include the following script on your payment page. This script must be loaded directly from sdk.ceevo.com.

in order to remain PCI compliant, hosting it your own or offline copies are not an option.

The Payment Widget SDK can be setup by loading it from sdk.ceevo.com


<script src="https://sdk.ceevo.com/ceevo.js"></script>

Certain parameters are required to activate the Payment Widget SDK, these are:

Parameter Description Example
apiKey APIKey of your account 136656b7-0d33-406d-9702-e4f09fa0736fTEST
formId Name of the payment form with leading hash #paymentForm
lang Display Language en
renderWidget toggle control false
envMode Mode of environment, TEST or LIVE TEST

Once parameters are set, activate the Payment Widget SDK with the following JavaScript code:


var apiKey = '136656b7-0d33-406d-9702-e4f09fa0736fTEST';
var formId = '#paymentForm'; // required

var ceevoPayment = new CeevoPayment(apiKey, formId, {lang: 'en',renderWidget: false, envMode: 'TEST'});

Before activating the Payment Widget SDK, you can assign an error callback to a DIV element for error display and handling.

errorDiv is the sample DIV for errors:


<div id='errorDiv' class="error-msg"></div>
ceevoPayment.addErrorCallBack((error) => {
            document.getElementById('errorDiv').innerHTML = '';
            document.getElementById('errorDiv').innerHTML = error;
        });

Once all parameters have been set, include the Payment Widget SDK in your payment form.


var elements = ceevoPayment.elements();
var card = elements.card();

card.renderTo('#card_info_div')

Payment Widget SDK

Resulting Tokens

Once the customer has checked out, collected account details are verified and processed by Ceevo. The following data is returned and appended to the payment form automatically.

Name Description Example
ceevo_sessionId Operation Session Id 7ed0ab2c-f5aa-4f3d-84aa-e2d6c5488f34
ceevo_tokenise Account Token 78103004-fa5c-42ab-9d6c-50592e0ffd36

These tokens, along with other payment form data, are sent to your server. Both tokens are required when calling the Charge API. This will be covered in the following section.

API Integration Guide

Use Ceevo's API and your server-side code to process payments. Ceevo API are using REST technology and JSON for data exchange.

Content-Type: application/json

The above HTTP header is required when calling the Ceevo API from your server-side code.

Ceevo API support Customer-Initiated Transactions (CIT), where a customer is present and makes a transaction; i.e. online checkout. It is recommended to enable 3DSecure for such transactions. Ceevo supports versions 3DS 1.0 and 3DS 2.0.

The Ceevo API supports Merchant-Initiated Transactions (MIT) where payment is processed when customer is absent from the transaction flow. Subscription and other recurring billing are examples of MIT.

Customer and Account Token

Once your customer’s account details have been collected and tokenized using the Payment Widget SDK, you can store the account token for later use.

To store an account token, following these steps:

Create Customer in Ceevo


POST /customer HTTP/1.1
Host: api.ceevo.com
Authorization: Bearer access_token_xxxxxxxxxx
Content-Type: application/json

{
  "billing": {
    "street": "50 Colorado Way",
    "zip": "HR3 4EX",
    "country": "GB"
  },
  "email": "[email protected]",
  "firstName": "Nicholas",
  "lastName": "Curtis",
  "mobile": "07789695310"
}

Unique ID of a customer can be found in the HTTP response.


HTTP/1.1 201 Created
Location: http://api.ceevo.com/customer/34bad767-345e-4da4-a7f8-addfgfdf3dbe5

Register Customer with Account Token

Linking a Customer with an Account Token requires one API call. In addition to payment details, you can store and verify provided customer address information with the payment card attribute by setting the verify parameter to true.


POST /customer/34bad767-345e-4da4-a7f8-addfgfdf3dbe5 HTTP/1.1
Host: api.ceevo.com
Authorization: Bearer access_token_xxxxxxxxxx
Content-Type: application/json

{
  "accountToken": "78103004-fa5c-42ab-9d6c-50592e0ffd36",
  "default": true,
  "verify": true
}

Status of registration, along with verification result, can be found in the HTTP response.


HTTP/1.1 200 Ok
{
  "customerId": "34bad767-345e-4da4-a7f8-addfgfdf3dbe5",
  "accountToken": "78103004-fa5c-42ab-9d6c-50592e0ffd36",
  "cvvMatch": false,
  "addressMatch": true
}

CIT Payment

Once your customer’s payment details are collected and tokenized using the Payment Widget SDK, you can charge the card immediately.

Unlike Payment Widget SDK which runs in the browser, payment attempts are made from your server.

Follow the steps below to process CIT with 3DSecure Authentication:

Send Payment to /charge API

 POST /charge HTTP/1.1
 Host: api.ceevo.com
 Authorization: Bearer access_token_xxxxxxxxxx
 Content-Type: application/json

 {
 "3dsecure": true,
 "accountToken": "81b39244-dd6b-4a5b-9030-3e10ae7bdc02",
  "amount": 10100,
  "currency": "EUR",
  "methodCode": "CARDS",
  "redirectUrls": {
    "successUrl": "https://www.merchant.com/success",
    "failureUrl": "https://www.merchant.com/failure"
  },
  "referenceId": "YourReference",
  "sessionId": "d6eaa343-d2ae-4f5a-8626-dab52ff2801c",
  "userEmail": "[email protected]"
 }

Charge API request example with description

Parameter Description
3dsecure Indicate transaction shall / shall not go through 3DSecure Authentication, recommended : true for CIT
accountToken Account Token returned from Payment Widget SDK
amount Amount in the smallest unit, 10100 represent Amount in 101.00
currency ISO-3 Currency Code
methodCode Payment Method to be used in this transaction
redirectUrls.successUrl Payment Page to redirect customer when transaction is successful
redirectUrls.failureUrl Payment Page to redirect customer when transaction has failed
referenceId Transaction Reference from your system
sessionId Session Id returned from Payment Widget SDK
userEmail Email Address of the cardholder

Handle 3DSecure User Redirection

Once the charge request is sent to Ceevo, user is required to authenticate themselves with their issuing bank.

The following data will be available in HTTP response.

 HTTP/1.1 302 Found
 Location: http://api.ceevo.com/redirect/34bad767-355e-4da4-a7f8-ad464df3dbe5

 {
    "statusCode": "PENDING",
    "message": "Y2IxYjllZTEtNTE2Yy00NjBmLWEwYTktZDJjYzRiZmJjMDNl",
    "paymentId": "b33a5830-787a-44c1-804a-8733e8e968f9"
 }

Charge API response example with description

Parameter Description
Location The URL where cardholder shall be redirected to authenticate with issuing bank
statusCode status code of this transaction in Ceevo
message one-time encryption key to authenticate callback from Ceevo in next step
paymentId Unique Transaction Id in Ceevo

Handle callback from Ceevo

Once cardholder authentication is complete, the cardholder will be redirected to successUrl / failureUrl once transaction complete at Ceevo.

Transaction result in JSON format will be sent to your system during this callback.

Response details are as below:

Parameter Description
statusCode status code of this transaction in Ceevo
description Status Description
paymentId Unique Transaction Id in Ceevo
referenceId Transaction Reference from your system
amount Amount in the smallest unit, 10100 represent Amount in 101.00
currency ISO-3 Currency Code
user Email Address of the cardholder
transactionDate Transaction Datetime in Ceevo

This callback makes use of the cardholder browser session in sending data back to your server. The transaction result is sent on top of an additional encryption layer to prevent data tampering.

The transaction result JSON data is compacted and encrypted using the one-time encryption key. The following data will be send to the successUrl / failureUrl in hidden fields.

Parameter Description
payload Base64 encoded encrypted transaction result JSON payload
HMACSHA256 HMACSHA256 checksum of transaction result JSON payload

CIT with existing Customer

Once a customer account is registered, payment details collected and tokenized using the Payment Widget SDK there is no need to ask a customer to provide their payment details again at checkout for subsequent transactions.

When collecting customer payment details, Card Verification Value (CVV) much be collected from the customer for each transaction despite all other payment details being stored and tokenized.

Follow the steps below to process CIT for existing customers with 3DSecure Authentication:

Send Payment to /charge API

 POST /charge HTTP/1.1
 Host: api.ceevo.com
 Authorization: Bearer access_token_xxxxxxxxxx
 Content-Type: application/json

 {
  "3dsecure": true,
  "customerId":"34bad767-345e-4da4-a7f8-addfgfdf3dbe5",
  "cvv":"123",
  "amount": 10120,
  "currency": "EUR",
  "methodCode": "CARDS",
  "redirectUrls": {
    "successUrl": "https://www.merchant.com/success",
    "failureUrl": "https://www.merchant.com/failure"
  },
  "referenceId": "YourReference",
  "sessionId": "d6eaa343-d2ae-4f5a-8626-dab52ff2801c"
 }

Required parameters are similar to those required for processing a CIT Payment except for userEmail and accountToken, as these parameters aren't needed. Please note, it is necessary to collect Card Verification Value (CVV) for each transaction for cardholder verification.

The rest of the payment flow is identical to processing a CIT Payment.

Plugins

Overview

We offer plugin support for numerous eCommerce platforms. Supported platforms include:

Errors

Ceevo API uses the following error codes during RESTful communication:

Error Code Meaning
200 Ok
201 Object / transaction Created
302 Customer Redirection is required, check Location header for URL
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your APIKey / access token is wrong.
404 Not Found -- The specified object could not be found.
405 Method Not Allowed -- You tried to access an object with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
500 Internal Server Error -- We had a problem with our server. Try again later.