This document is a draft / work in progress as this API is still in development. Please contact us, if you would like to begin using this API.

About Payment API

Mozello Payment API allows integration of third party payment gateways into Mozello online stores and Mozello platform itself. There are two types of integration for different use cases:

  • Private integration - you want to use a third party payment gateway for your own Mozello store
  • Public integration - you represent a payment gateway and want to offer your service to all Mozello customers

The technology is similar in both use cases, however public integration involves some extra steps and is subject to approval by Mozello, whereas private integration can be done and tested without involvement from Mozello.

Basics

Developers host their payment processing pages on their own infrastructure. You can host your payment processing page anywhere, and build it with the tech stack of your choice.

When user is ready to make payment and Checkout button is pressed, Mozello will make an HTTP POST request to a predefined payment URL specified under Catalog > Catalog settings > Payment > Credit cards / payment platforms > API.

The POST request will contain the following fields:

  • order_id – a unique, numeric order identifier
  • invoice_id – a unique invoice number e.g. M-1234567890-1234567890
  • amount – a total amount, for example, 10.02
  • currency – a 3-letter currency identifier, for example, EUR, USD
  • first_name – the first name of the buyer, as entered
  • last_name – the last name of the buyer, as entered
  • company – the name of the company, as entered
  • company_id – the company ID, as entered
  • company_vat – the company VAT ID, as entered
  • email – the email address of the buyer, as entered
  • street – the street address of the buyer, as entered
  • city – the city of the buyer, as entered
  • state – the state of the buyer, as entered
  • zip – the postal code of the buyer, as entered
  • country_code – a 2-letter country code, for example, es (Spain), de (Germany)
  • language_code – a 2-letter user interface language code, for example en (English), lv (Latvian)
  • alias – alias name of Mozello website
  • success_url – a URL address to redirect after a successful payment
  • failure_url – a URL address to redirect after a failed payment
  • notify_url – a URL address to send a payment status notification back to Mozello
  • optional custom fields in case of public integration; these come from integration settings form defined in the public integration manifest and filled-in by the particular Mozello online store admin upon selecting your payment gateway from the list of available gateways. Examples: client ID, project ID, client's API key, sandbox mode etc. - whatever the way your payment gateway identifies and authenticates your merchants.
  • signature – signature hash computed on a string resulting in concatenation of your API key and the rest of the POST field data

You then have all the necessary data to take full control over handling the payment process and displaying the payment interface. Depending on the result of the payment (either a success or a failure), you should redirect the end-user back to success_url or failure_url.

Once the payment status is confirmed, you must send a POST request to notify_url to notify Mozello about the successful payment. Set following fields in such POST request:

  • order_id – the unique public order identifier
  • status – send "approved" (without quotes) if the purchase was successful
  • signaturesignature hash

Payment process step by step

  1. End-user (shop customer) selects your platform as the payment method and clicks the Checkout button.
  2. Mozello sends an HTTP POST request to the specified payment URL hosted on your own infrastructure. The request contains basic information about the purchase – the amount, currency, order ID etc.
  3. Your server receives the request from Mozello and communicates with the payment gateway in one of two ways (depending on the payment gateway API):
    - Show the UI and communicate with the payment processing gateway API in the background, or
    - Redirect to a hosted payment page of the payment processing gateway
  4. You receive a response or redirect back from the payment processing gateway.
  5. Based on the response, your payment page redirects back to the corresponding Mozello shop page - success_url or failure_url, depending on whether the payment was a success.
  6. Your server also notifies Mozello abut payment status via server-to-server POST request to the notify_url about a successful payment.

Authentication

Getting your API secret key

For private integration, you will find your per-website API key under Catalog > Catalog settings > Payment > Credit cards / payment platforms > API.

For public integration, you will receive your global Mozello API key when signing up via Payment platform integration setup portal.

Request signing

Payment confirmation requests have to contain digital signature in a signature parameter.

Similarly, POST redirect requests to your payment URL will contain digital signature in the signature POST parameter.

Computing signature hash

The signature hash is computed by running a sha256 HMAC hash function on the concatenation of string data of all request data fields except signature.

Pseudo code for generating signature for payment confirmation

message = order_id + status
signature = HMAC_SHA256(message, api_key)

PHP example for generating signature for payment confirmation

// prepare data array for POST request
$data = array(
    'order_id' => $order_id,
    'status' => 'approved'
);
// generate data string
$message = '';
foreach ($data as $key => $value) {
    if ($key != 'signature') {
        $message = $message . $value;
    }
}
// calculate signature hash and add it to POST data
$data['signature'] = base64_encode(hash_hmac('sha256', $message, $api_key, true));

PHP example for validating received POST data

// generate data string
$message = '';
foreach ($_POST as $key => $value) {
    if ($key != "signature") {
        $message = $message . $value;
    }
}
// calculate signature hash
$signature = base64_encode(hash_hmac('sha256', $message, $api_key, true));
// check if hash matches
if ($signature == $_POST['signature']) {
    // Your code here
}

Considerations

  • You need a web server that will host your integration pages / code and act as an intermediary between Mozello and the payment processing gateway. Mozello will not install your code on our servers, instead this is done by your code hosted on your own infrastructure.
  • HTTPS (SSL) connecton is mandatory

Public integration

Use case

Public integration may be of interest to payment gateways and payment processing companies that want to offer their services to all Mozello customers.

How it works?

The public integration technology and process is very similar to private, individual integration described above, but with the following benefits to the payment gateway:

  • Payment gateway is added to the list of available payment platforms for all Mozello users (subject to filtering by country)
  • Any qualified online store on Mozello platform can use the integration
  • Payment gateway receives a publication on our list of supported payment processing platforms.

With public integration, the store admin does not have to specify any payment API URL, instead they select your payment platform from the drop down of available payment platforms and fill in the setup form that may consist of one or more fields defined by your platform (e.g. platform API key, customer ID, password etc.) that are passed to your API URL as an additional POST parameters.

The integration process

Prerequisites:

  • Understanding of this API
  • You need to be an accredited, established payment gateway

The process:

  1. Create a Mozello account for testing
  2. Contact us for access to Payment platform integration setup portal
  3. Submit your integration manifest via Payment platform integration setup portal and receive your secret key
  4. Create and test your integration
  5. Submit your integration for approval via Payment platform integration setup portal
  6. Upon successful approval, your integration will go live
  7. Update your integration details via Payment platform integration setup portal any time
  8. If you provide pricing details, Mozello will list your gateway on our supported payment processing platforms page

Public integration manifest

Public integration partners will have to submit a structured data manifest (in JSON format) containing information about your platform and integration credentials that will allow Mozello to show integration settings UI and to reuse single payment API URL for multiple merchants.

Upon signing up and submitting the manifest, you will enable sandbox environment for integration development and receive a global (as opposed to per-website as in private integration) secret key that will be used to compute hashes.

Manifest example

{
    "app_type": "PAYMENT_GATEWAY",
    "app_title": "Fancy Payment Gateway",
    "payment_api_url": "https://hosted-payment-pages/fancypaymentgateway.com",
    "company_name": "Fancy Payment Gateway Inc",
    "support_email": "support@fancy-payment-gateway.example",
    "support_phone": "+555 1234 1234",
    "developer_email": "dev@fancy-payment-gateway.example",
    "payment_api_data_fields": [
        {
            "id": "customer_id",
            "title": {
                "en": "Your Customer ID",
                "de": "Ihre Kundennummer"
            },
            "type": "text",
            "required": true
        },
        {
            "id": "api_key",
            "title": {
                "en": "Your Secret Key",
                "de": "Dein geheimer Schlüssel"
            },
            "type": "password",
            "required": true
        },
        {
            "id": "is_sandbox",
            "title": {
                "en": "Sandbox mode",
                "de": "Sandbox-Modus"
            },
            "type": "checkbox",
            "required": false
        },
        {
            "id": "use_3d_secure",
            "title": {
                "en": "3D secure mode",
                "de": "3D-Sicherheitsmodus"
            },
            "type": "dropdown",
            "required": false,
            "items": [
                {
                    "title": "Auto",
                    "value": "0",
                    "default": true
                },
                {
                    "title": {
                        "en": "Always",
                        "de": "Immer"
                    },
                    "value": "1"
                },
                {
                    "title": {
                        "en": "Never",
                        "de": "Noch nie"
                    },
                    "value": "2"
                }
            ]
        }
    ],
    "payment_platform_info": {
        "available_in_countries": ["US", "UK", "DE"],
        "supported_payment_methods": {
            "visa": true,
            "mc": true,
            "maestro": true,
            "amex": true,
            "paypal": true
        },
        "info_url": {
            "en": "https://fancypaymentgateway.com",
            "de": "https://fancypaymentgateway.com/de/"

        },
        "pricing_url": {
            "en": "https://fancypaymentgateway.com/pricing/",
            "de": "https://fancypaymentgateway.com/de/preise/"
        }
    }
}

Manifest reference

  • app_type - mandatory, always PAYMENT_GATEWAY
  • app_title - mandatory, title in the list of payment gateways. Non-localizable string
  • payment_api_url - mandatory, your payment API URL
  • company_name - mandatory, name of company that represent the payment gateway
  • support_email - mandatory, support e-mail
  • support_phone - mandatory, support phone number
  • developer_email - mandatory, e-mail for informing about critical and breaking API changes
  • payment_api_data_fields - array of payment data field object, this data will be collected from user and passed in POST requests
    • id - field id (form data parameter name)
    • title - field label. Either string or languages object
    • type - field type - text, password, checkbox, email
    • required - if the field is mandatory
  • payment_platform_info - for display and promotional purposes
    • available_in_countries - 2-letter ISO country code - which Mozello users will see the platform
    • supported_payment_methods - this is used for showing logos where necessary
      • visa
      • mc
      • maestro
      • amex
      • discover
      • jcb
      • unionpay
      • paypal
      • swedbank
      • seb
      • luminor
      • citadele
      • lhv
    • info_url - either string or languages object
    • pricing_url - either string or languages object