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.

Payment processing flow

Mozello Payment API

  1. End-user (shop customer) clicks the Checkout button.
  2. Mozello sends an HTTP POST request to the specified payment URL (payment_api_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.

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 Store > Store settings > Payment > Credit cards / payment platforms > API for private integration OR in the payment_api_url parameter submitted via your integration manifest for public integration.

The POST request will contain the following fields:

  • order_uuid – the universally unique order identifier
  • invoice_id – the invoice number that user and customer sees e.g. M-1234567890-1234567890
  • amount – a total amount, for example, 10.02
  • currency – a 3-letter currency identifier, for example, EUR, USD
  • billing_first_name – the first name of the buyer, as entered
  • billing_last_name – the last name of the buyer, as entered
  • billing_company – the name of the company, as entered
  • billing_company_id – the company ID, as entered
  • billing_company_vat – the company VAT ID, as entered
  • billing_email – the email address of the buyer, as entered
  • billing_street – the street address of the buyer, as entered
  • billing_city – the city of the buyer, as entered
  • billing_state – the state of the buyer, as entered
  • billing_zip – the postal code of the buyer, as entered
  • billing_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)
  • website_alias – alias name of Mozello website, e.g. supershop (for supershop.mozello.com)
  • website_domain – domain name of the online shop, for example, www.example.com
  • 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
  • signature – signature hash computed on a string resulting in concatenation of your API key and the rest of the POST field data

In case of public integration, you can request values of the optional custom fields by making a server to server request to https://api.mozello.com/v1/payment/payment_settings/. Send order_uuid that you just received and api_key as plain GET or POST parameters. You will receive JSON encoded custom fields that 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.

Example returned custom fields:


{
    "error": false,
    "fields": {
        "customer_id": "1234567890",
        "api_key": "*****",
        "use_3d_secure": "0",
        "enable_banklink": "0"
    },
    "meta": {
        "notify_url": "https://www.mozello.com/service/ipn/provider/xxx/",
        "success_url": "https://www.my-wonderful-mozello-test-shop.com/shop/params/success/go/",
        "failure_url": "https://www.my-wonderful-mozello-test-shop.com/shop/params/failure/go/"
    }
}

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 payment status. Set following fields in such POST request:

  • order_uuid – the universally unique order identifier
  • status – send "approved" (without quotes) if the purchase was successful or "failed" if it failed
  • check_pending (optional) - set to 1 to allow payment status changed only if it's still in pending state and not already set (e.g. by user manually), otherwise error will be returned with info about the current payment status.
  • signature – signature hash

Authentication

Getting your API secret key

For private integration, you will find your per-website API key under Store > Store 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_uuid + status
signature = HMAC_SHA256(message, api_key)

PHP example for generating signature for payment confirmation

// prepare data array for POST request
$data = array(
    'order_uuid' => $order_uuid,
    '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",
    "app_vendor": {
        "company_name": "Fancy Payment Gateway Inc",
        "support_email": "support@fancypaymentgateway.com",
        "support_phone": "+1 555 0100 1234",
        "developer_email": "dev@fancypaymentgateway.com"
    },
    "payment_api_url": "https://fancypaymentgateway.com/mozello-payment-api-page",
    "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": "Ihre geheimen Schlüssel"
            },
            "type": "text",
            "required": true
        },
        {
            "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": "Niemals"
                    },
                    "value": "2"
                }
            ]
        },
        {
            "id": "enable_banklink",
            "title": {
                "en": "Enable bank-links",
                "de": "Bankverbindungen aktivieren"
            },
            "type": "checkbox",
            "required": false
        }
    ],
    "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

* denotes mandatory fields

  • app_type * - always PAYMENT_GATEWAY
  • app_title * - title in the list of payment gateways, non-localizable string
  • app_vendor * - info about the developer of the integration
    • company_name * - name of company that represent the payment gateway
    • support_email * - support e-mail
    • support_phone * - support phone number
    • developer_email * - e-mail for informing about critical and breaking API changes
  • payment_api_url * - your payment API URL
  • 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, checkbox, email
    • required - if the field is mandatory
  • payment_platform_info - for display and promotional purposes
    • available_in_countries - array of 2-letter ISO country code - which Mozello users will see the platform
    • supported_payment_methods - this is used for showing logos where necessary
      • visa
      • mastercard
      • 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