Online shop – Помощен център

Introduction

The Online API was created to allow online shops to easily and quickly connect an additional payment method for orders - "Mokka - payment in advance".

"Mokka - payment in advance" is an instant possibility for the buyer to pay for purchases in online shops. Our system will divide your payment into equal installments according to a schedule agreed upon beforehand by the customer. After the schedule has been approved, Mokka will immediately transfer the money for your purchase.

Using the Online API methods you can register a customer in Mokka, pay for a purchase in advance, make a cancellation or return an order. Using the Online API on your website will require minimal modifications on the shop frontend. Online API is based on REST architecture, which allows you to easily communicate with the Mokka system. You will only need to implement the payment method, adjust the price display and place the marketing material on the website strictly according to Mokka's guidelines.

Business Process

Supported business processes via Online API

Online shopping from partner shops
Deferred payments
Cancellation of order by Partner
Return of purchased goods by the customer

Registration

The process is initiated by the customer at the time of registration through a banner on the home screen or through an orange Mokka price shown in the product card.

The customer clicks on the Mokka banner or on the orange Mokka product price shown in the product card;
The partner sends Registration request to Mokka with all available customer information;
Mokka sends the partner a link to a prepared registration form;
Partner displays the Mokka registration form on its website through the iFrame;
The new customer enters the missing data into the registration form (the current user clicks the Login button and enters the phone number) and confirms his consent to the use of his personal data by starting a limit request;
The customer confirms the registration of the application by entering the SMS code received by him;
Mokka calculates and returns the limit available to the customer

Checkout
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 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.

Cancel
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 Cancel 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.

Return
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 Return request to Mokka ;
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)

Integration steps

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

Deployment: initial familiarization and testing of Online API support (usually performed at the partner's test environment).
Functional Testing: Find and fix errors that may occur when sending and processing requests.
Placement of marketing materials on the partner's side (must meet the visualization requirements set by the company).
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 are done on the test server:

https://demo-backend.mokka.pl — Poland
https://demo-backend.mokka.ro — Romania
https://demo-backend.mokka.bg — Bulgaria

The Postman collections to test API are:

https://share.mokka.team/mokka-iframe-pl-ext.postman_collection.zip — Poland
https://share.mokka.team/mokka-iframe-ro-ext.postman_collection.zip — Romania
https://share.mokka.team/mokka-iframe-bg-ext.postman_collection.zip — Bulgaria

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

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

Example of creating a digital signature on ruby

The content of the JSON request is written into the variable data :
1. data = "{"order_id": \"FACTPRECHR152632\", \"amount\": \"8300.00\"}"
The variable secret_key contains the name of the key:
1. secret_key = "9fff8c602b08b00323567be0001480f6"
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:

In the request URL field, enter a header with your digital signature and the store ID you received.

POST https://stage-backend.revoplus.pl/ {API URL}?store_id=01&signature=34738cff27d30b5200c8b32def4365ebbf4270d0

In the Body section, enter the text of the callback received in the earlier step, after running the puts command.

{
      "callback_url": "https://shop.bg/revo/decision",
      "redirect_url": "https://shop.bg/revo/redirect",
      "primary_phone": "9267654321",
      "primary_email": "LOGIN@MAIL.com",
      "current_order":
      {
          "order_id": "R001234"
      }
  }

Test

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

Obtaining a customer limit using the Register method;
Making a purchase using the Checkout method;
Cancelling a completed order using the Cancel method;
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
Bulgarian version demo.mokka.bg

After pressing: Send Request Order after selecting payment from Mokka

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.

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

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

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.

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:

Launch

After successfully completing all the previous integration steps, you are ready to receive payments using Avansa Mokka. To start accepting payments, you need to contact the Mokka integration manager to transfer your online store to combat mode and receive commercial settings from it, such as store_id and secret_key battle keys, as well as the base URL of the server for sending combat requests.

By replacing the test settings with commercial ones, you provide customers with access to the Mocha advance, which will significantly increase the number of sales of your online store and reduce the number of carts abandoned at the checkout stage.