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"
- 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.
- https://demo-backend.mokka.pl - the
BASE_URL
- variable containing the base address.
Authorization parameters
Parameters example
secret_key = "e662c46b5bef24a96c3128e25f43beaa05e3bd13"
STORE_ID1 = 12
- 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.
- For authorization, the partner sends POST query, using digital signature and unique store identifier
store_id
. - 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.