{
  "status": 0,
  "message": "Payload valid",
  "iframe_url": "https://stage-backend.revoplus.pl/form/v1/af45ef12f4233f"
}

Checkout method

The Checkout method is available for those who would like to use the Mokka payment method. The method consists of a Registration and transaction. The Registration step is the same as shown in the diagram above. The transaction step is shown below. The customer can make a transaction only if the limit granted is greater than the purchase amount. 

The client chooses the payment method "Mokka - Payment in advance" by making a purchase in the partner's online store The partner sends a Checkout request to Mokka, transmitting all the available information about the client Mokka gives the partner a link to the prepared order form; The partner displays the Mokka order form on his website The client enters the missing data into the registration form (the current user clicks the "Login" button and enters the phone number) and confirms consent to the use of his personal data by launching the application Mokka decides on the possibility of issuing an advance payment to the client, calculates the payment schedules available to the client, and informs the partner and the client about the decision The client chooses a suitable repayment period for the advance, and agrees with the proposed payment schedule, confirming the purchase; Mokka updates the loan by changing the status to HOLD, and sends a callback to the partner store. The partner picks up information and marks the payment as “Authorized”, similarly to blocking the amount on credit card The client receives a notification of a successful purchase The partner delivers the order and sends the purchase receipt The partner sends a Finish request to Mokka, including the purchase receipt, to transfer the sales contract for service to Mokka Mokka sends a register of transactions through the partner's API, and transfers funds to the partner's account for the assignment of the right to claim a debt from the client in favor of Mokka.

Request Json query

{
  "terms_url": "https://mokka.ro/landings/demostore/",
  "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": "john.connor@gmail.com",
  "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": "sarah.connor@gmail.com",
    "type": "Pickpoint",
    "address": "McKinley street 1"
  },
  "additional_data":
  {
    "previous_url": "https://revo.ru/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": "john.connor@gmail.com",
    "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
  }]
}

Response example in case of successful authentication.

{
  "status": 0,
  "message": "Payload valid",
  "iframe_url": "https://stage-backend.revoplus.pl/factoring/v1/form/6976174c5b6a1bb089d15b80e0a6afc62d4283fe"
}

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 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": "john.connor@gmail.com",
    "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
  }]
}

Status method

The Status method allows you to retrieve the current status of the customer's loan decision and the status of the loan process in Mokka. Possible cases with a detailed description are presented in the section below.

Request Json query

 {
   "order_id": "R107356"
 }

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

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

Finish Method

The Finish method is launched by the online store when it is certain that the order can be completed. Then the store sends a request with information about the order number and the amount. This method is very important in the customer lending process and was marked in the diagram during the checkout process. As the moment of completing the loan process. Finalizing an order that has already been expired status will result in execution of `Cancel` method.

{
  "order_id": "R107356",
  "amount": 6700.00,
  "check_number": "ZDDS3123F"
}

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

Parameter Name	Type	Description
status	integer	Response code.
Message	String	A short text description of the response.

 

 

Cancel method

The method enables the cancellation of an order placed in the online store by the customer. The process is initiated by the customer when cancelling an order placed on the partner's website.

The customer cancels an order on the website or through the partner support service; The partner sends a cancellation request to Mokka; Mokka cancels the advance and restores the customer's limit; Partner receives confirmation of the cancellation of the down payment and issues a cancellation of the order.

Json query example

{
  "order_id": "R107356"
}

Parameter Name	Type	Description
order_id	integer	Unique order number

Response example in case of successful document upload.

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

Parameter Name	Type	Description
Status	integer	Response Code
Message	String	A short text description of the response.

Return method

With this method, the customer can return the goods purchased in the online store.

The process is initiated by the Customer when he/she makes a full or partial return of the purchased goods.

The customer makes a partial or full return of the goods; Partner sends a request for Mokka to return; Mokka confirms that the advance payment can be cancelled; The partner receives confirmation of the cancellation of the down payment and returns the payment for the goods to Mokka; Mokka performs actions depending on the type of return: Partial return of goods: Partial restoration of the customer's limit according to the amount of the refund; Recalculate the payment schedule according to the new purchase amount; Full turnaround: Full restoration of customer limit; Return the balance to the customer (funds already deposited by the customer as an advance payment)

 

Json query example

{
  "order_id": "R001233",
  "amount": 2010.00
}

Parameter Name	Type	Description
order_id	integer	Unique order number
amount	float	Amount to be returned. A return can either be full or partial.

 
Json response example in case of successful return

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

Parameter Name	Type	Description
Status	integer	Response Code
Message	string	A short text description of the response.

 

Integration steps

The integration process with Mokka Online API includes the following steps:

1. Deployment: initial familiarization and testing of Online API support (usually performed at the partner's test environment).
2. Functional Testing: Find and fix errors that may occur when sending and processing requests.
3. Placement of marketing materials on the partner's side (must meet the visualization requirements set by the company).
4. Launch: receive the merchant settings from the Mokka integration manager and start accepting payments.

 

Implementation

At this stage you should familiarize yourself with the procedure of using Online API, the rules of generating and sending requests to the service and prepare the texts of the requests for debug testing.

Testing and debugging requests during integration is done on the test server: https://stage-backend.revoplus.pl/— POLAND

https://stage-backend.mokka.ro/— ROMANIA

 

Test parameters

To test Online API, you need to get the test parameters from mokka integration manager:

• identifier - store_id
• key - secret_key

Online API is implemented using HTTPS based on JSON requests. Requests are sent using the POST method.

 

API methods

Method	Name	Description of the Request	API URL
POST	Registration	Granting of a Limit	factoring / v1 / limit / auth
POST	Checkout	Transaction in the Online Shop	factoring / v1 / precheck / auth
POST	Finish	Finalizing transactions	factoring / v1 / precheck / finish
POST	Limit	Downloading the customer's current limit	api / external / v1 / client / limit
POST	Status	Download order status	factoring / v1 / status
POST	Schedule	Downloading a payment schedule	factoring / v1 / schedule
POST	Change	Change in the contract amount	factoring / v1 / precheck / change
POST	Cancel	Cancellation of an order	factoring / v1 / precheck / cancel
POST	Return	Return of order (full or partial)	factoring / v1 / return

 

Authorization

Every API request requires authorization. To process the request, you must generate an authorization header that contains:

• https://stage-backend.revoplus.pl/ – the base URL of the service (test);
• store_id – the unique identifier of the store received from Mokka;
• signature – digital signature generated from JSON request text and secret_key.

Procedure for generating a digital signature

1. Prepare a valid JSON request;
2. Transform the request text by adding an extra "\" before each " and "\" character;
3. Add the secret key received from Mokka to the result;
4. Apply the SHA1 encryption algorithm to the last line.
5. The result is a 40-character digital signature to be added to the request header.

Example of creating a digital signature on ruby

1. The content of the JSON request is written into the variable data :
   1. data = "{"order_id": \"FACTPRECHR152632\", \"amount\": \"8300.00\"}"
2. The variable secret_key contains the name of the key:
   1. secret_key = "9fff8c602b08b00323567be0001480f6"
3. The signature is formed into a signature variable:
   1. signature = Digest::SHA1.hexdigest(data + secret_key)
   2. signature = "347e8cff27d30b5200c8b32def4365ebbf4270d0"

Once the signature has been generated correctly, you can send the request to our system by adding it to the request header.

Here is a sample query:

1. In the request URL field, enter a header with your digital signature and the store ID you received.
   1. POST https://stage-backend.revoplus.pl/ {API URL}?store_id=01&signature=34738cff27d30b5200c8b32def4365ebbf4270d0
2. API URL - This URL from API Methods API URL
   
   1. In the Body section, enter the text of the callback received in the earlier step, after running the puts command.
   2. {"callback_url": "https://shop.ru/revo/decision", "redirect_url": "https://shop.ru/revo/redirect", "primary_phone": "9267654321", "primary_email": "LOGIN@MAIL.com", "current_order":{"order_id": "R001234"}}

 

API Tests

Now that you have established proper communication with Mokka API, you can test our Environment. The test scenario below gives you an in-depth look at the purchasing process. API testing procedure

1. Obtaining a customer limit using the Register method;
2. Making a purchase using the Checkout method;
3. Cancelling a completed order using the Cancel method;
4. Return an order using the Return method.

When sending test requests, it is recommended to pass parameters that meet the following conditions:

• Phone number – must start with a 333 prefix, so text messages are not sent to real people
• The confirmation code and pin code is 1111 (the code for testing on the production Server is set in the partner settings).

Additional Documentation with sample requests is in https://docs.mokka.pl/ The scenarios for each stage are described below.

Obtaining the Limit – Registration

Steps	Result
1. Submitting a Registration Request	Getting a link to an iframe
2. Calling iframe_url	Displaying iframe
3. Filling out the form with non-existent data in the database (phone numbers in the format +7 (888) 221XXXX) and pressing the "Send SMS" button	Go to the stage of confirmation by SMS code
4. Enter the confirmation code: 8888	Displaying the result screen with information about the unavailability of the installment service

Obtaining a Limit – Existing Customer

Steps	Expected Result
1. Submitting a Registration Request	Getting a link to an iframe
2. Calling iframe_url	Displaying iframe
3. Filling in the form with non-existent data in the database (phone numbers in the format +7 (888) 22XXXXX) and pressing the "Send SMS" button	Go to the stage of confirmation by SMS code
4. Enter the confirmation code: 8888	Displaying the result screen with information about the approved limit

Checkout method with an existing customer

Steps	Result
Sending a transaction request	Answer with Link
Calling an iframe from a Link	Display of iframe
Entering the phone number of an existing customer	SMS Pin request, schedule display
Acceptance of the payment schedule	Transaction summary

Checkout method with a new customer

Steps	Result
Sending a Checkout Request	Getting a link to an iframe
2. Calling iframe_url	Displaying iframe
3. Pressing the "Enter" button, entering the phone number and pressing the "Send SMS" button	Go to the stage of confirmation by SMS code
4. Enter the confirmation code: 1111	Display of the result screen with information about the approved advance and the payment schedule
5. Sending a Finish request with the attached check.pdf file.	Receiving a positive response (status = 0)

 

 

Cancellation of an order

Steps	Expected Result
1. Sending a Checkout Request	Getting a link to an iframe
2. Calling iframe_url	Displaying iframe
3. Pressing the "Enter" button, entering the phone number and pressing the "Send SMS" button	Go to the stage of confirmation by SMS code
4. Enter the confirmation code: 1111	Display of the result screen with information about the approved advance and the payment schedule
5. Sending Request Cancel	Receiving a positive response (status = 0)
6. Sending Status Request	Receiving response: decision = approved status = canceled

 

Return of an order

Steps	Result
1. Sending a Return request with order_id = order number from clause 2.1 and amount = total cost of the order	Receiving a positive response (status = 0)
2. Sending Status Request	Receiving response: decision = approved status = refunded

 

If the details of an existing user are entered, the current limit of that user should appear. Special clients number for testing:

• 333 XXX 610 – Rejection of application (blocked client)
• 333 XXX 630 – Rejection of application (client limit it’s not enough)
• 333 XXX 681 – Rejection of application (overdue client)
• 333 XXX XXX – Acceptance of application

Possible error codes

The code	Message	Description
0	Payload valid	All OK
10	JSON decode error	Invalid Request
20	order_id missing	Order_id not specified
21	Wrong order_id format	Invalid order_id format
22	Order exists	An order with the given order_id already exists and is finalized
23	Order expired	An order with the given order_id has already expired
24	Order with specified ID not found	The order with the specified order_id was not found
30	Wrong order amount format	Amount is not in the correct format (decimal places are required)
31	Wrong order prepayment amount format	Prepayment amount is not in the correct format (decimal places must be specified)
32	Order amount is different from the amount specified before	The order amount indicated during finalization differs from the amount for which the order was made. Finalization not completed
33	Order amount is outside of tariff limits	The amount of the application is not included in the range set in the partner's tariff. Application not created
34	Order term value is wrong	An incorrect value of the term for the maturity of the advance payment is specified (there is no such tariff)
35	Order prepayment amount is wrong	The prepayment amount is the amount
40	Order callback_url missing	Callback_url not specified
41	Order redirect_url missing	Redirect_url not specified
50	Store ID is missing	Store_id not specified
51	Store not found	No store found with the specified store_id
60	Signature missing	No digital signature specified
61	Signature wrong	The specified digital signature is invalid
62	Error saving file	Error saving file
70	Phone number is different	The phone number is different from the one specified in the application
71	Client has not enough limit	The client does not have enough funds to pay in parts of the order
80	Unable to finish – order is already finished / canceled	Unable to finalize the order – the order with the specified order_id has already been finalized or canceled
81	Unable to cancel – order is already finished / canceled	Unable to cancel the order – the order with the specified order_id has already been finalized or canceled
82	Unable to change – order is already finished / canceled	Unable to change the order – the order with the specified order_id has already been finalized or canceled
90	Cart items are missing	Unable to change the application – the information about the basket was not transmitted
100	At the moment, the server cannot process your request	In all other cases
110	Invalid time format value	Invalid order validity format valid till
404	Not found	The connection must be made using the HTTPS protocol

 

 

Marketing Materials

At this stage, Mokka marketing materials are published on the site. There are certain requirements for the provision of the Mokka service on the partner's side. During the integration, it is necessary to:

Place the item "Mokka - payment in advance" among the payment methods. Buyers have the option to receive a loan from Mokka and pay immediately.

Marketing Materials can you see on:

• Romania version demo.mokka.ro
• Polish version demo.mokka.pl/

After pressing: Send Request Order after selecting payment from Mokka

2. Place a banner on the home page opening a form through which the customer can register and find out the amount of advance available to him without leaving the store.

When pressed: Sends a registration request when the banner is clicked.

3. Customize the display of the broken price on the tab of each product. The broken price will show the customer the amount of monthly payment when they purchase the item using the down payment.

After hitting the mokka banner: Send a registration request to Mokka

4. Place the Mokka payment system logo in the footer of your site (bottom of pages).

5. Add a Mokka landing page. On the landing page, the customer can read the detailed terms and conditions, register and find out the amount of down payment available to them, as well as get answers to frequently asked questions. The content of the landing page is provided in the form of an iframe.

After clicking: Opens the Mokka page after clicking on an element.

6. Add information about the possibility to use Mokka in the "Delivery & payment" section (or similar). In addition, partner's employees who work with customers should read the Mokka Terms of Service listed at https://mokka.pl/pomoc/.

7. You can see what the finished solution looks like at www.demo.mokka.
   

Integration Summary

This is a checklist of your implementation Online API

  Test Connection with Mokka Online API.

  Get Credential for Authentication on Mokka Online API.   Test Authorization with Mokka Online API.

  Test Main Method.

  Check all business processes for obtaining a Limit, Buy with Mokka, Cancel payment, and Return partial or full of your order.

  Test the bad scenario with block, overdue and no limit clients, with special phone numbers.

  Add Mokka Marketing Materials into your order section.

  Create a demo account and provide username and password with a link to Mokka on your own environment, so that we can audit and test your implementation.

  Contact us at integration