NAV Navbar
  • Introduction
  • Authorization
  • API Methods
  • iFrame generation
  • Error codes
  • Testing
  • Introduction

    API is based on the HTTPS protocol with JSON queries. Designed for online stores.

    The documentation consists of 3 main parts:

    Authorization

    Base URL addresses

    
    BASE_URL = "https://demo-backend.mokka.pl"
    BASE_URL = "https://demo-backend.mokka.ro"
    BASE_URL = "https://demo-backend.mokka.bg"
    
    1. To interact with Mokka services, two base addresses are used:
      • https://demo-backend.mokka.pl - the demo address of the Polish service.
      • https://demo-backend.mokka.ro - the demo address of the Romanian service.
      • https://demo-backend.mokka.bg - the demo address of the Bulgarian service.
    2. BASE_URL - variable containing the base address.

    Authorization parameters

    Parameters example

    secret_key = "e662c46b5bef24a96c3128e25f43beaa05e3bd13"
    STORE_ID1 = 12
    
    1. On Mokka's side a unique store identifier and a secret key are generated, which are transferred to the partner:
      • store_id - unique store identifier.
      • secret_key - a secret key used when generating the digital signature for authentication of query parameters to protect the form from being launched by third parties. Encryption algorithm is SHA1.
    2. For authorization, the partner sends POST query, using digital signature and unique store identifier store_id.
    3. Examples of URL queries can be found in API Methods section.

    Digital signature generation

    Algorithm of digital signature generation

    require 'digest/sha1'
    secret_key = 'e662c46b5bef24a96c3128e25f43beaa05e3bd13'
    data = "{\"order_id\": \"FACTPRECHR152632\", \"amount\": \"8300.00\"}"
    SIGNATURE = Digest::SHA1.hexdigest(data + secret_key)
    

    The result of the encryption in the above example is "36d0433a9e0f063748f88e903c74f2b65443ac3d".

    import java.io.UnsupportedEncodingException;
    import java.security.MessageDigest;
    import java.security.NoSuchAlgorithmException;
    import java.util.Formatter;
    
    public class Main {
    
        static String secret_key = "e662c46b5bef24a96c3128e25f43beaa05e3bd13"; 
        static String data = "{\"callback_url\":\"https://shop.example.com/revo/decision\",\"redirect_url\":\"https://shop.example.com/revo/redirect\",\"current_order\":{\"amount\":\"7500.00\",\"order_id\":\"R001233\"},\"primary_phone\":\"654456546\"}";
    
        public static void main(String[] args) {
    
            String signature = encryptPassword(data + secret_key); // Тут всегда будет 40 символов по SHA1
            System.out.println(signature);
        }
    
        private static String encryptPassword(String password) {
            String sha1 = "";
            try {
                MessageDigest crypt = MessageDigest.getInstance("SHA-1");
                crypt.reset();
                crypt.update(password.getBytes("UTF-8"));
                sha1 = byteToHex(crypt.digest());
            } catch(NoSuchAlgorithmException e) {
                e.printStackTrace();
            } catch(UnsupportedEncodingException e) {
                e.printStackTrace();
            }
            return sha1;
        }
    
        private static String byteToHex(final byte[] hash) {
            Formatter formatter = new Formatter();
            for (byte b : hash) {
                formatter.format("%02x", b);
            }
            String result = formatter.toString();
            formatter.close();
            return result;
        }
    }
    

    A secret key secret_key is added to an escaped (adding \ in front of " and \) json body data string. SHA1 algorithm is then used to the generate a string which forms a digital signature.

    API Methods

    Registration

    POST BASE_URL/factoring/v1/limit/auth?store_id=STORE_ID1&signature=SIGNATURE
    

    The method returns a URL to the iFrame in order to get the client's limit. Upon completion of the form a json response with information about client's limit is sent to the address specified in callback_url.

    Depending on the information about the user in the Mokka system the form will have a different number of steps (primary_phone has to be specified) - see more info on iFrame generation.

    Parameters

    Json query example

    {
      "iframe_kind": "pop up",
      "callback_url": "https://shop.example.com/revo/decision",
      "redirect_url": "https://shop.example.com/revo/redirect",
      "authorized_client": true,
      "primary_phone": "654456546",
      "primary_email": "[email protected]",
      "current_order":
      {
        "order_id": "119R"
      },
      "person":
      {
        "first_name": "John",
        "surname": "Connor",
        "patronymic": "",
        "birth_date": "15.01.1975"
      }
        "additional_data":
      {
        "previous_url": "https://mokka.com/where-to-buy",
        "returning_customer": true,
        "bank_card": true,
        "last_orders": "1",
        "sum_orders": 10000.0,
        "client":
          {
            "client_id": "541USR",
            "registration_date": "11.11.2021",
            "data_change_date": "15.11.2021",
            "purchases_value": 1,
            "purchases_sum": 10000.0,
            "first_purchase_date": "11.11.2021",
            "last_purchase_date": "11.11.2021",
            "uniq_user_phone": 1
          }
        "purchase":
          [{
            "product_name": "Selphone Xiaomi mi 8",
            "number": 1,
            "product_price": 10000.00
          }]
      }
    }
    
    iframe_kind
    string, optional
    Changes iframe opening behavior: popup/page. Use "page" option to open iframe as a separate page or "popup" to open iframe over your page. If the field is empty the iframe will open in "popup" mode.
    callback_url
    string
    URL for Mokka response with information about client's limit.
    redirect_url
    string
    URL for redirecting upon clicking the button "Return to online store” in the Mokka form.
    authorized_client
    bool
    Flag which shows if customer is logged in on the merchant's account.
    primary_phone
    string, optional
    Client phone number from merchant's account (without country code).
    primary_email
    string, optional
    Client email from merchant's account
    current_order
    object
    An object containing information about the order.
    order_id
    string
    Unique order number. Maximum 255 characters. A unique random string can be used.
    person
    object, optional
    An object containing information about the client from merchant's account
    first_name
    string, optional
    Client’s name.
    surname
    sring, optional
    Client’s surname.
    patronymic
    string, optional
    Client's patronymic.
    birth_date
    object, optional
    Client’s birth date in dd.mm.yyyy format.
    additional_data
    object
    An Object containing additional order information.
    previous_url
    string
    Previous url client came from.
    returning_customer
    bool, optional
    Flag which shows if customer made a purchase for the last 24 month.
    bank_card
    bool, optional
    Flag which shows if customer made a payment with bank card for the last 24 month.
    last_orders
    integer, optional
    Number of all orders client made for the last 24 month.
    sum_orders
    float, optional
    Value of all orders client made for the last 24 month.
    client
    object, optional
    An object containing additional information about the client saved on partner's website.
    client_id
    string, optional
    Client ID.
    registration_date
    string, optional
    Date of registration of the client in the format dd.mm.yyyy.
    data_change_date
    string, optional
    Date of the last change of the client data in the format dd.mm.yyyy. (name, birth date, phone number, email, document)
    purchases_value
    integer, optional
    Number of purchases from successful orders for the last 24 month.
    purchases_sum
    float, optional
    Value of purchases from succesful orders for the last 24 month.
    first_purchase_date
    string, optional
    The date of customer's first purchase in the format dd.mm.yyyy.
    last_purchase_date
    string, optional
    The date of the customer's last purchase in the format dd.mm.yyyy.
    uniq_user_phone
    string, optional
    Number of unique clients with primary_phone in merchant's client base
    purchase
    array
    An array containing additional information about 3 previous purchases.
    product_name
    string, optional
    Product name.
    number
    integer, optional
    Product quantity.
    product_price
    float, optional
    Purchase cost.

    Response Parameters

    Response example in case of successful authentication.

    {
      "status": 0,
      "message": "Payload valid",
      "iframe_url": "https://demo-backend.mokka.pl/form/v1/af45ef12f4233f"
    }
    
    status
    integer
    Response code.
    message
    string
    A short text description of the response.
    iframe_url
    string
    URL to the generated iFrame.

    Callback parameters

    For security, the system sends in the GET parameter signature. Signature is SHA1.hexdigest(data + secret_key). Data is a callback body.

    Callback example in case of successful authentication.

    {
      "order_id": "32423",
      "decision": "approved",
      "amount": 5000.00,
      "mobile_phone": "657588485",
      "email": "[email protected]"
    }
    
    order_id
    string
    Unique order number. Maximum 255 characters.
    decision
    string
    Decision on instalments. In case of positive decision - approved (the order is waiting to be finalized). In case of negative decision - declined.
    amount
    float
    Amount.
    mobile_phone
    string
    Client’s phone number consisting of 9 digits (omitting the country code).
    email
    string
    Client's email.

    Limit

    POST BASE_URL/api/external/v1/client/limit?store_id=STORE_ID1&signature=SIGNATURE
    

    The method for obtaining the client’s limit amount using his phone number. Not applicable for new customers.

    Parameters

    Json query example

    {
      "client":
      {
        "mobile_phone": "654456546"
      }
    }
    
    client
    object
    An object containing information about the client.
    mobile_phone
    string
    Client’s phone number consisting of 9 digits (omitting the country code).

    Response Parameters

    Response example in case of a returning customer

    {
      "meta":
      {
        "status": 0,
        "message": "Payload valid"
      },
      "client":
      {
        "mobile_phone": "654456546",
        "limit_amount": "9500.00",
        "status": "active"
      }
    }
    

    Response example in case of a returning customer with installments products unavailable

    {
      "meta":
      {
        "status": 0,
        "message": "Payload valid"
      },
      "client":
      {
        "mobile_phone": "654456546",
        "limit_amount": "6700.00",
        "status": "inactive"
      }
    }
    

    Response example in case of a new customer

    {
      "meta":
      {
        "status": 0,
        "message": "Payload valid"
      },
      "client":
      {
        "mobile_phone": "654456546",
        "limit_amount": "0.00",
        "status": "new"
      }
    }
    
    status
    integer
    Response code.
    message
    string
    A short text description of the response.
    client
    object
    An object containing information about the client.
    mobile_phone
    string
    Client’s phone number consisting of 9 digits (omitting the country code).
    limit_amount
    string
    The amount of funds available to the client.
    status
    string
    User status. Possible values:
    active - the installments product is available to the user;
    inactive - the installments product is unavailable to the user;
    new - a new user with installments product available.

    Checkout

    POST BASE_URL/factoring/v1/pre_check/auth?store_id=STORE_ID1&signature=SIGNATURE
    

    The method returns a URL to the iFrame for client's order registration. Upon completion of the form a json response with information about order registration is sent to the address specified in callback_url. In case of successful registration amount is withheld from clinent's funds in the Mokka system. The merchant system should send response HTTP 200 and include the text "ok" in the body.

    Depending on the information about the user in the Mokka system the form will have a different number of steps (primary_phone has to be specified) - see more info on iFrame generation.

    In case where prepayment is needed, there are 2 ways of prepayment implementation: * If prepayment is made prior to opening the iFrame, then the prepayment amount should be sent using prepayment_amount. * If prepayment is to be made after the iFrame is called, the corresponding setting on the Mokka side is made. Parameter skip_result_page should be set as true and redirect_url should be set to the prepayment page, to which the client will be redirected upon the completion of registration in Mokka iFrame.

    Parameters

    Json query example

    {
      "callback_url": "https://shop.example.com/revo/decision",
      "checkout_url": "https://shop.example.com/revo/checkout",
      "redirect_url": "https://shop.example.com/revo/redirect",
      "authorized_client": true,
      "primary_phone": "654456546",
      "primary_email": "[email protected]",
      "skip_result_page": true,
      "current_order":
      {
        "order_id": "120R",
        "amount": 51000.0,
        "tax_amount": 0.0,
        "discount_amount": 0.0,
        "prepayment_amount": 1000.0,
        "valid_till": "21.07.2018 12:08:01+03:00"
      },
      "person":
      {
        "first_name": "John",
        "surname": "Connor",
        "patronymic": "",
        "birth_date": "15.01.1975"
      },
      "cart_items":
      [{
        "SKU": "441R",
        "name": "Samsung Note 8",
        "price": 48000.0,
        "tax_price": 0.0,
        "quantity": 1,
        "quantity_unit": "pcs",
        "category": "Phone"
      },
      {
        "SKU": "530C",
        "name": "Phone cover",
        "price": 3000.0,
        "tax_price": 0.0,
        "quantity": 1,
        "quantity_unit": "pcs",
        "category": "Accessories"
      }],
      "delivery_info":
      {
        "first_name": "Sarah",
        "surname": "Connor",
        "patronymic": "",
        "phone": "654456546",
        "email": "[email protected]",
        "type": "Pickpoint",
        "address": "McKinley street 1"
      },
      "additional_data":
      {
        "previous_url": "https://mokka.com/where-to-buy",
        "returning_customer": true,
        "bank_card": true,
        "last_orders": 2,
        "sum_orders": 61000.0,
        "same_address": true,
        "client":
        {
        "first_name": "John",
        "surname": "Connor",
        "patronymic": "",
        "phone": "654456546",
        "email": "[email protected]",
        "client_id": "654456546",
        "registration_date": "11.11.2021",
        "data_change_date": "15.11.2021",
        "purchases_value": 2,
        "purchases_sum": 61000.0,
        "first_purchase_date": "11.11.2021",
        "last_purchase_date": "11.11.2021",
        "uniq_user_phone": "1"
      },
      "purchase":
      [{
        "product_name": "Selphone Xiaomi mi 8",
        "number": 1,
        "product_price": 10000.0
      }]
    }
    
    callback_url
    string
    URL for Mokka response with information about client's limit.
    checkout_url
    string
    URL for redirecting if client request was regected
    redirect_url
    string
    URL for redirecting upon clicking the button "Return to online store” in the Mokka form.
    authorized_client
    string
    Flag which shows if customer is logged in on the merchant's account.
    primary_phone
    string
    Client phone number from merchant's account (without country code).
    primary_email
    string
    Client email from merchant's account
    skip_result_page
    bool, optional
    A flag that determines whether the results page of the iFrame will be displayed. The default value is false.
    true - upon successful registration completion the user is immediately redirected to redirect_url.
    false - upon successful registration completion the user is presented with result page.
    current_order
    object
    An object containing information about the order.
    order_id
    string
    Unique order id. Maximum 255 characters.
    amount
    float
    Total order amount.
    tax_amount
    float
    Tax amount for the order.
    discount_amount
    float
    Discount amount for the order.
    prepayment_amount
    float
    The amount already prepaid by the client.
    valid_till
    string, optional
    The period during which the order is considered to be valid (funds are withheld for this period of time). When this period expires, the order will be cancelled. Format: dd.mm.yyyy hh:mm:ss+hh:mm, where hh:mm after "+" is the time zone relative to GMT. The default value is 24 hours.
    person
    object
    An object containing information about the client from merchant's account
    first_name
    string
    Client name.
    surname
    sring
    Client surname.
    patronymic
    string, optional
    Client patronymic.
    birth_date
    string, optional
    Client birth date in dd.mm.yyyy format.
    cart_items
    array
    An array containing information about current order cart.
    SKU
    string
    Uniq product undetifier.
    name
    string
    Product name.
    price
    float
    Product price.
    tax_price
    float
    Product tax amount.
    quantity
    integer
    Product quantity.
    quantity_unit
    integer
    Product quantity descritption (kg,pcs,lt).
    category
    string, optional
    Product category.
    delivery_info
    object
    An object containing information about the delivery.
    first_name
    string
    Receiver name.
    surname
    string
    Receiver surname.
    patronymic
    string,optional
    Receiver patronymic.
    phone
    string
    Receiver phone number (without country code).
    email
    string, optional
    Receiver email.
    type
    string
    Delivery type. Possible values: store pick-up, pick-up point, registered box, unregistered box courier, shipping company.
    address
    string
    Delivery address.
    additional_data
    object
    An object containing additional order information.
    previous_url
    string
    Previous url client came from.
    channel
    string
    In which channel form is opened. Possible values: mobile, app, desktop.
    returning_customer
    bool
    Flag which shows if customer made a purchase for the last 24 month.
    bank_card
    bool
    Flag which shows if customer made a payment with bank card for the last 24 month.
    last_orders
    string
    Number of all orders client made for the last 24 month.
    sum_orders
    string
    Value of all orders client made for the last 24 month.
    same_address
    bool
    Flag which shows if delivery address is the same as previous.
    client
    object
    An object containing additional information about the client saved on partner's website.
    first_name
    string
    Client name from chekout step
    surname
    string
    Client surname from chekout step
    patronymic
    string, optional
    Client patronomics from chekout step
    phone
    string
    Client phone number from chekout step (without country code)/td>
    email
    string
    Client email from chekout step
    client_id
    string
    Client id saved in partner system.
    registration_date
    string
    Date of registration of the client in the format dd.mm.yyyy.
    data_change_date
    string
    Date of the last change of the client data in the format dd.mm.yyyy. (name, birth date, phone number, email, document)
    purchases_value
    integer
    Number of purchases from successful orders for the last 24 month
    purchases_sum
    float
    Value of purchases from succesful orders for the last 24 month
    first_purchase_date
    string
    The date of customer's first purchase in the format dd.mm.yyyy.
    last_purchase_date
    string
    The date of the customer's last purchase in the format dd.mm.yyyy.
    uniq_user_phone
    integer
    Number of unique clients with primary_phone in merchant's client base
    purchase
    array
    An array containing information about 5 previous succesful orders.
    product_name
    string
    Product name.
    number
    integer
    Product quantity.
    product_price
    float
    Purchase cost.

    Response Parameters

    Response example in case of successful authentication.

    {
      "status": 0,
      "message": "Payload valid",
      "iframe_url": "https://demo-backend.mokka.pl/factoring/v1/form/6976174c5b6a1bb089d15b80e0a6afc62d4283fe"
    }
    
    status
    integer
    Response code.
    message
    string
    A short text description of the response.
    iframe_url
    string
    URL to the generated iFrame.

    Callback parameters

    For security, the system sends in the GET parameter signature. Signature is SHA1.hexdigest(data + secret_key). Data is a callback body.

    Callback example in case of success order registration.

    {
      "order_id": "R107356",
      "payment_id": "ABC123",
      "decision": "approved",
      "amount": 2500.00,
      "prepayment_amount": 100.00,
      "total_amount": 2600.00,
      "term": 3,
      "client":
      {
        "primary_phone": "654456546"
        "email": "[email protected]",
        "full_name": "John Connor",
        "first_name": "John",
        "surname": "Connor",
        "patronymic": ""
      },
      "schedule":
      [{
        "date": "2018-01-01",
        "amount": 2933.33
      },
      {
        "date": "2018-02-01",
        "amount": 2933.33
      },
      {
        "date": "2018-03-01",
        "amount": 2933.33
      }]
    }
    
    order_id
    string,
    Unique order number. Maximum 255 characters. A unique random string can be used.
    payment_id
    string,optional
    Unique payment identification. Maximum 255 characters.
    decision
    string
    Decision on instalments. In case of positive decision - approved (the order is waiting to be finalized). In case of negative decision - declined.
    amount
    float
    Amount withheld from client's Mokka account.
    prepayment_amount
    float, optional
    The amount already prepaid by the client.
    total_amount
    float, optional
    Total order amount, including prepayment.
    term
    integer
    Installments period in months.
    client
    object
    An object containing information about the client.
    primary_phone
    string
    Client’s phone number consisting of 9 digits (omitting the country code).
    primary_email
    string, optional
    Client’s email.
    full_name
    string
    Client's full name: last name, first name and patronymic diveded by spaces.
    first_name
    string
    Cleint's first name.
    surname
    sring
    Client's last name.
    patronymic
    string
    Client's patronymic.
    schedule
    object
    Object containing information about the payment schedule.
    date
    string
    Payment date in yyyy-mm-dd format.
    amount
    float
    Payment amount.
    monthly_overpayment
    float
    Monthly overpayment amount.

    Schedule

    POST BASE_URL/factoring/v1/schedule?store_id=STORE_ID1&signature=SIGNATURE
    

    The method returns information on the available preliminary payment schedules for the specified purchase price.

    Parameters

    Json query example

    {
      "amount": 5000.00
    }
    
    amount
    float
    Amount withheld from client's Mokka account.

    Response Parameters

    Response example in case when 2 payment schedules are available: 3 and 6 months.

    {
      "status": 0,
      "message": "Payload valid",
      "payment_schedule":
      [{
        "total": 7000.01,
        "monthly_payment": 2334,
        "monthly_overpayment": 666.67,
        "term": 3,
        "payment_dates":
        [{
          "date": "2018-06-08",
          "amount": 2334.00
        },
        {
          "date": "2018-07-08",
          "amount": 2334.00
        },
        {
          "date": "2018-08-08",
          "amount": 2332.01
        }]
    }
    
    message
    string
    A short text description of the response.
    payment_schedule
    object
    Object containing information about the payment schedule.
    total
    float
    Total order amount, including overpayment.
    monthly_payment
    float
    Monthly payment amount.
    monthly_overpayment
    float
    Monthly overpayment amount.
    term
    int
    Installments period in months.
    payment_dates
    object
    Object containing information about the payment schedule.
    date
    string
    Payment date in yyyy-mm-dd format.
    amount
    float
    Payment amount.

    Status

     POST BASE_URL/factoring/v1/status?store_id=STORE_ID1&signature=SIGNATURE
    

    The method returns information on the order status.

    Parameters

    Json query example

     {
       "order_id": "R107356"
     }
    
    order_id
    string
    Unique order number. Maximum 255 characters. A unique random string can be used.

    Response Parameters

    Response example in case when the client has completed the registration process (Mokka iFrame) and is awaiting the Partner response

    {
      "status": 0,
      "message": "Payload valid",
      "current_order":
      {
        "order_id": "FACTPRECHR00004768",
        "expired": false,
        "status": "hold",
        "decision": "approved",
        "amount": 4999.0,
        "term": 3
      }
    }
    

    Response example in case when the client has completed the registration process (Mokka iFrame) and the Parter has cancelled the order.

    {
      "status": 0,
      "message": "Payload valid",
      "current_order":
      {
        "order_id": "FACTPRECHR00004768",
        "expired": true,
        "status": "canceled",
        "decision": "approved",
        "amount": 4999,
        "term": 3
      }
    }
    

    Response example in case when the client has completed the registration process (Mokka iFrame) and the Partner has confirmed the order.

    {
      "status": 0,
      "message": "Payload valid",
      "current_order":
      {
        "order_id": "FACTR00004755",
        "expired": false,
        "status": "finished",
        "decision": "approved",
        "amount": 1000,
        "term": 3
      }
    }
    

    Response example in case when the order was declined by Mokka

    {
      "status": 0,
      "message": "Payload valid",
      "current_order":
      {
        "order_id": "FACTPRECHR00004721",
        "expired": true,
        "status": "declined",
        "decision": "declined",
        "amount": 6498,
        "term": null
      }
    }
    

    Response example in case when funds withholding period has elapsed. The order is cancelled.

    {
      "status": 0,
      "message": "Payload valid",
      "current_order":
      {
        "order_id": "FACTPRECHR141531",
        "expired": true,
        "status": "expired",
        "decision": "approved",
        "amount": 9000,
        "term": 3
      }
    }
    

    Response example in case when the client has completed the registration process (Mokka iFrame) and the Partner has confirmed the order. Then the order has been returned.

    {
      "status": 0,
      "message": "Payload valid",
      "current_order":
      {
        "order_id": "FACTPRECHR00004714",
        "expired": true,
        "status": "refunded",
        "decision": "approved",
        "amount": 734.51,
        "term": 3
      }
    }
    
    status
    integer
    Response code.
    message
    string
    A short text description of the response.
    current_order
    object
    An object containing information about the order.
    order_id
    string
    Unique order number. Maximum 255 characters. A unique random string can be used.
    expired
    bool
    Flag showing the current order status (funds withholding). The value is false for valid orders and true for expired orders (valid_till date and time has come).
    status
    string
    Order status information. Possible values:
    pending, hold, finished, canceled, expired, declined, refunded.
    decision
    string
    Decision on instalments. In case of positive decision - approved (the order is waiting to be finalized). In case of negative decision - declined.
    amount
    float
    Total order amount.
    term
    integer
    Installments period in months.

    Status and Decision values

    Mokka decision Order status Description
    null pending The client was not authorized during the checkout process in the form (entered phone number but didn't confirm it with SMS code). No limit decision has been made.
    approved pending The client entered personal data and confirmed the phone number with the SMS code, but did not choose a term of instalments and did not complete the transaction.
    approved hold Client's limit is approved, funds are withheld and the order is avaiting finalization by the store.
    approved finished Order is finalized by the store. In case of subsequent expiration or in case of partial return this status doesn't change.
    approved canceled Order is cancelled. In case of subsequent expiration this status doesn't change.
    approved expired Client's limit is approved, order expired.
    approved refunded Order was fully refunded. In case of partial return status is qual to finished.
    approved declined Client's limit is approved, installments product is unavailable to the client (order amount is above client's limit).
    declined declined Client's limit is declined by Mokka.

    Change

    POST BASE_URL/factoring/v1/pre_check/change?store_id=STORE_ID1&signature=SIGNATURE
    

    Method for changing an order.

    Parameters

    Json query example

    {
      "order_id": "R107356",
      "amount": 48000.0,
      "valid_till": "29.07.2018 12:08:01+03:00"
      "cart_items":
      [{
        "name": "Samsung Note 8",
        "price": 48000,
        "quantity": 1,
        "quantity_unit": pcs
      }]
    }
    
    order_id
    string
    Unique order number. Maximum 255 characters. A unique random string can be used.
    amount
    float
    Total order amount.
    valid_till
    String, optional
    A period during which the order is considered to be valid (funds are withheld for this period of time). When this period expires, the order is cancelled. Format: dd.mm.yyyy hh:mm:ss+hh:mm, where hh:mm after "+" is the time zone relative to GMT. The default value is 24 hours.
    cart_items
    object
    An object containing information about the order.
    name
    string
    Product name.
    price
    float
    Product price.
    sale_price
    float, optional
    Product price in case of discount (if available).
    quantity
    integer
    Product quantity.
    quantity_unit
    string, optional
    Unit of measurement of the cart item, e.g. pcs.

    Response parameters

    Response example in case of successful change.

    {
      "status": 0,
      "message": "Payload valid",
      "schedule":
      [{
        "date": "2018-01-01",
        "amount": 2933.33
      },
      {
        "date": "2018-02-01",
        "amount": 2933.33
      },
      {
        "date": "2018-03-01",
        "amount": 2933.33
      }]
    }
    
    status
    integer
    Response code.
    message
    string
    A short text description of the response.
    schedule
    object
    Object containing information about the payment schedule.
    date
    string
    Payment date in yyyy-mmm-dd format.
    amount
    float
    Payment amount.

    Cancel

    POST BASE_URL/factoring/v1/pre_check/cancel?store_id=STORE_ID1&signature=SIGNATURE
    

    Method for order cancellation. The whitheld amount of client's funds is unblocked upon cancellation.

    Parameters

    Json query example

    {
      "order_id": "R107356"
    }
    
    order_id
    string
    Unique order number. Maximum 255 characters. A unique random string can be used.

    Response Parameters

    Response example in case of successful order cancellation.

    {
      "status": 0,
      "message": "Payload valid"
    }
    
    status
    integer
    Response code.
    message
    string
    A short text description of the response.

    Finish

    POST BASE_URL/factoring/v1/pre_check/finish?store_id=STORE_ID1&signature=SIGNATURE
    

    Method for finalizing the order by transferring the sales contract to Mokka. The query content type is multipart/form-data. Two keys have to be specified in the query: the first one named 'body' that contains the json query and the second one named check where the file (fiscal document, i.e. receipt) is attached. Signature is formed in the usual way - without the second key.

    Parameters

    Json query example

    {
      "order_id": "R107356",
      "amount": 6700.00,
      "check_number": "ZDDS3123F"
    }
    
    order_id
    string
    Unique order number. Maximum 255 characters.
    amount
    float
    Amount.
    check_number
    string, optional
    Fiscal document number according to Partner's system (i.e. receipt number).

    Response Parameters

    Response example in case of successful document upload.

    {
      "status": 0,
      "message": "Payload valid"
    }
    
    status
    integer
    Response code.
    message
    string
    A short text description of the response.

    Return

    POST BASE_URL/factoring/v1/return?store_id=STORE_ID1&signature=SIGNATURE
    

    Method for performing a full or partial return. Only a finalized order can be returned. For unfinalized orders Cancel method has to be used.

    Parameters

    Json query example

    {
      "order_id": "R001233",
      "amount": 2010.00
    }
    
    order_id
    string
    Unique order number. Maximum 255 characters.
    amount
    float
    Amount to be returned. A return can either be full or partial.

    Response Parameters

    Json response example in case of successful return

    {
      "status": 0,
      "message": "Payload valid"
    }
    

    Json response example in case of unsuccessful return

    {
      "status": 10,
      "message": "JSON decode error"
    }
    
    status
    integer
    Response code.
    message
    string
    A short text description of the response.

    iFrame generation

    REVO.Form.showPopup(iframe_url);
    REVO.Form.show(iframe_url, target_selector);
    

    Mokka Checkout iFrame has to be called when "Pay with Mokka" button is clicked on the checkout page. That is performed by generating a link with Registration or Checkout methods and sending the link to a js method from Mokka plugin.

    Method showPopup(iframe_url); allows showing popup with the form on the page.

    Method show(iframe_url, target_selector); allows showing the form inside the selector.

    iframe_url – iFame URL, obligatory parameter. target_selector – element selector that will contain the iFrame.

    Mokka JS plugin then inserts <iframe src= iframe_url /> and processed iFrame operations.

    Plugin is available at the following address: https://{BASE_URI}/javascripts/iframe/v2/revoiframe.js.

    <script src="https://{BASE_URI}/javascripts/iframe/v2/revoiframe.js"></script>
    

    Plugin also supports the following events: form closed - onClose, form loaded - onLoad, decision made - onResult.

    REVO.Form.onClose(function () { alert('closed'); });
    REVO.Form.onLoad(function () { console.log('frame loaded'); });
    REVO.Form.onResult(function() { console.log('result'); });
    

    Error codes

    Code Message Comments
    0 Payload valid Everything is OK.
    10 JSON decode error Incorrect json query.
    20 Order order_id missing
    21 Wrong order order_id format
    22 Order exists Order with specified order_id already exist and is finalized.
    23 Order expired Order with specified order_id has expired.
    24 Order with specified id not found
    32 Order amount is different from the amount specified before Occurs when trying to finalize an order with incorrect amount.
    33 Order amount is outside of tariff_limits Order amount is outside of tariff limits specified for the partner.
    34 Order term value is wrong Incorrect term value is specified.
    35 Order prepayment amount is wrong prepayment_amount is greater than amount.
    40 Order callback_url missing
    41 Order redirect_url missing
    50 Store id is missing
    51 Store not found Unable to find store with specified store_id.
    60 Signature missing
    61 Signature wrong
    62 Error saving file
    70 Phone number is different
    71 Client has not enough limit Client has insufficient funds for the specified order.
    80 Unable to finish - order is already finished/canceled
    81 Unable to cancel - order is already finished/canceled
    82 Unable to change - order is already finished/canceled
    84 Unable to return - order is already fully paid. The contract with Mokka has been closed. Please contact directly to Customer regarding the return.
    90 Cart items are missing Unable to change order - no cart_items specified.
    100 At the moment the server cannot process your request Occurs in any other cases.

    Testing

    Integration testing is performed on demo server (eg. https://demo-backend.mokka.pl).

    All confirmation codes and pin codes are 1111.

    Phone number, full name, email and identification data (eg. ID card number, PESEL, CNP) is checked for an existing client. This has to be taken into account when testing.

    А list of frequently asked questions is displayed in the upper right corner of the form when clicking on the FAQ button.

    Displaying client's available funds

    Funds available to the already registered client might be obtained using the Limit method.