Mirakl – Daily Usage

The HiPay Marketplace cash-out integration for Mirakl is intended to be used with a cron, but can be used directly from the command line. In fact, this software is supposed to execute tasks automatically, which is why you need to configure cron jobs (or any other alternative) that will execute commands at the appropriate time automatically. Please note that default values for command line arguments/parameters are defined in the parameters.yml file. There are 4 main commands that need to be run automatically by relying on cron jobs:
      • Vendor processing,
      • Cash-out generation,
      • Transfer processing,
      • Withdrawal processing.
There are also two debug and one update commands that do not need to be run using a cron job:
      • Listing wallet accounts,
      • Getting bank information,
      • Recovering vendor logs from past executed cron.

Notifications  

In some cases, the HiPay integration for Mirakl can encounter errors or issues that cannot be managed automatically. In such a case, a notification is sent by email in order to inform you about the issue. The email recipient can be configured in the parameters.yml file. When this documentation refers to a “notification” being sent upon error, it means an email notification.

Vendor processing  

Command call $ php bin/console vendor:process Execution
      1. Retrieves the vendors from Mirakl.
      2. Saves the vendors: creates the HiPay account, if not already created, or gets the HiPay account number from HiPay.
      3. Validates them.
      4. Transfers the KYC files from Mirakl to the HiPay platform.
      5. Adds the bank information on the HiPay account, if not already done, or checks HiPay’s bank information against the data from Mirakl to make sure they match. If these are not the same, an error notification is sent.
Once the HiPay Marketplace cash-out integration for Mirakl is installed, you may call this method without the lastUpdate argument, just as below: $ php bin/console vendor:process This will make the command retrieve all the stores of your Mirakl instance and will synchronize all of them into the connector and into the HiPay platform. Then, the command may be run regularly with the lastUpdate parameter in order to only retrieve the new stores or the recently updated ones (please see the cron example). Argument
Name Type Required Description
lastUpdate Date No Date of the last update of Mirakl stores. If not provided, all stores will be retrieved.
Options
Name Type Description
tmpPath String Path where the documents should be saved temporarily before being sent to HiPay.
Cron example Please see below an example of how your cron job may be configured. Replace path/to/bin/console by the proper path to the console file. This command should be run as often as the vendors update their data. 0 */6 * * * php path/to/bin/console vendor:process “24 hour ago” In this cron example, the command will be run every 6 hours, retrieving the stores which have been updated in the last 24 hours. Retrieving the stores updated in the last 24 hours instead of the last 6 hours allows to handle some rare issues (for example, in case the command failed once because of a network issue disallowing it from reaching Mirakl or HiPay). In such a case, the stores would be synchronized on the next command call.

Cash-out generation  

Command call $ php bin/console cashout:generate Execution
      1. Retrieves the PAYMENT transactions from Mirakl to get all the invoices of the cycle.
      2. Gets the amount due to the vendors and the operator from the invoices.
      3. Creates the operations to be executed afterwards, validates and saves them.
      4. Adjusts operations amount to deal with past negative operations.
Argument
Name Type Required Description
cycleDate Date No Sets the cycle date
Options
Name Type Description
executionDate String Date to consider for cycle date computing
intervalBefore Interval Interval to subtract from cycleDate
intervalAfter Interval Interval to add to cycleDate
Cron example Please see below an example of how your cron job may be configured. Replace path/to/bin/console by the proper path to the console file. This command should be run right after the payment cycle has been made in Mirakl. 30 0 * * * php path/to/bin/console cashout:generate `date +%Y-%m-%d`

Transfer processing  

Command call $ php bin/console cashout:transfer Execution
      1. Executes, on the HiPay platform, the transfer of operations in statuses TRANSFER_NEGATIVE, TRANSFER_FAILED and CREATED (in this order).
Arguments This command doesn’t have any argument. Options This command doesn’t have any option. Cron example Please see below an example of how your cron job may be configured. Replace path/to/bin/console by the proper path to the console file. This command should be run when you have payments you want to transfer to your sellers (basically, after completion of the cashout:generate command). Moreover, this command also handles the operations in error. For example, if an operation failed because the HiPay account was not identified at that time, the operation processing should be retried later. Therefore, it’s a good practice to run this command once a day. In that case, this command will be run after the cashout:generate command and will also be run any other day in the month, in case operations would be in error. 0 2 * * * php path/to/bin/console cashout:transfer

Withdrawal processing  

Command call $ php bin/console cashout:withdraw Execution
      1. Executes, on the HiPay platform, the withdrawal of operations in statuses WITHDRAW_NEGATIVE, WITHDRAW_FAILED and TRANSFER_SUCCESS (in this order).
Arguments This command doesn’t have any argument. Options This command doesn’t have any option. Cron example Please see below an example of how your cron job may be configured. Replace path/to/bin/console by the proper path to the console file. This command should be run when you have payments you want to withdraw from your sellers’ wallet account and transfer to their bank account (basically, after completion of the cashout:transfer command). Moreover, this command also handles the operations in error. For example, if an operation failed because the HiPay account was not identified at that time, the operation processing should be retried later. Therefore, it’s a good practice to run this command once a day. 0 4 * * * php path/to/bin/console cashout:withdraw

Listing wallet accounts  

Command call $ php bin/console vendor:wallet:list Execution
      1. Retrieves the HiPay account information associated with a merchant group ID (associated with an entity).
      2. Displays it in a table.
Argument
Name Type Required Description
merchantGroupId Integer No Merchant group ID for retrieving HiPay accounts
Options This command doesn’t have any option.

Getting bank information  

Execution
      1. Retrieves the bank information status for a specific HiPay account ID.
      2. If that status is validated, displays the information stored by HiPay.
Argument
Name Type Required Description
hipayId Integer Yes HiPay account ID used to retrieve the bank information status
Options This command doesn’t have any option.

Recovering vendor logs 

Command call $ php bin/console logs:vendors:recover Execution
      1. Retrieves every saved vendor in the database.
      2. If a vendor has no log, creates one.
Argument This command doesn’t have any argument. Options This command doesn’t have any option.

Parameters  

The following table describes the data in the parameters.yml file. The user you run the commands with should have write access to all the paths you use in this file. Mirakl web service  
Name Type Default value Description
mirakl.frontKey String Mirakl API Front key (provided by Mirakl)
mirakl.operatorKey String Mirakl API Operator key (provided by Mirakl)
Mirakl cycles  
Name Type Default value Description
cycle.days Array [1, 11, 21] Array of days (1 to 28) on which the cycle is run in the month
cycle.hour Integer 0 Hour on which the cycle is run
cycle.minute Integer 0 Minute on which the cycle is run
cycle.interval.before String 12 hours Time to subtract from the cycle time to form an interval from which to fetch the transactions from Mirakl
cycle.interval.after String 12 hours Time to subtract from the cycle time to form an interval from which to fetch the transactions from Mirakl
HiPay  
Name Type Default value Description
hipay.wsLogin String HiPay web service login key for the technical account
hipay.wsPassword String HiPay web service password key for the technical account
hipay.baseUrl String Base URL to HiPay web service
hipay.entity String Provided by HiPay
hipay.locale String fr_FR Locale of created accounts. Format should be: languageCode_ISO3166-1 alpha-2 country code
hipay.timezone String Europe/Paris Time zone of created accounts. Please see the php manual for a list of time zones.
hipay.merchantGroupId Integer Provided by HiPay
hipay.transfer.withdraw.rest Boolean true Use REST api instead of SOAP api
HiPay accounts  
Name Type Default value Description
account.technical.email String Email of the HiPay technical account
account.technical.hipayId Integer ID of the HiPay technical account
account.operator.email String Email of the HiPay operator’s account
account.operator.hipayId Integer ID of the HiPay operator’s account
HiPay labels  
Name Type Default value Description
label.public String Public {{miraklId}} – {{hipayId}} – {{cycleDate}} Public label for HiPay transfers. Please see hereafter for more details.
label.private String Private {{miraklId}} – {{hipayId}} – {{cycleDate}} Private label for HiPay transfers. Please see hereafter for more details.
label.withdraw String Withdraw {{miraklId}} – {{hipayId}} – {{cycleDate}} Withdrawal label for HiPay withdrawals. Please see hereafter for more details.
Database  
Name Type Default value Description
db.driver String pdo_mysql PHP PDO driver. Please refer to the php manual for a list of PDO drivers.
db.host String DB hostname
db.username String DB username
db.password String DB password
db.name String DB name
db.port Integer DB port
Miscellaneous  
Name Type Default value Description
debug Boolean false Activates Debug mode
db.logger.level Integer 300 Minimum logging level at which this handler will be triggered
default.tmp.path String /tmp Default path to save the downloaded zip file
log.file.path String /var/log/hipay.log Path to the log file
cashout.transactionFilterRegex String null Used to filter cash-out transactions. Leave null if you don’t know what to do with it.
dashboard.locale String fr Default locale for the dashboard
Log level  
Label Value
DEBUG 100
INFO 200
NOTICE 250
WARNING 300
ERROR 400
CRITICAL 500
ALERT 550
EMERGENCY 600

Labels  

Labels give a description of the transaction (transfer or withdrawal) and appear on the account statement. For label parameters (label.public, label.private, label.withdraw), the following placeholder strings can be used, which will be replaced before sending the data to HiPay. Each string must be surrounded by {{ and }} to be replaced.
Placeholder Description
miraklId Store ID if it exists, or operator ID in case of an operator’s operation
amount Amount of the operation
hipayId HiPay account ID
cycleDate Cycle date of the operation
cycleDateTime Cycle date and time of the operation
cycleTime Cycle time of the operation
date Execution date of the operation
dateTime Execution date and time of the operation
time Execution time of the operation

Appendix  

Please find below the description of each operation status listed in the operations table.
Name Value Description
CREATED 1 The operation has been created.
ADJUSTED_OPERATIONS 2 The operation has been adjusted (concerns past negative operations).
TRANSFER_SUCCESS 3 The transfer has been executed with success.
TRANSFER_REQUESTED 4 The transfer has been requested with success.
WITHDRAW_REQUESTED 5 The withdrawal has been requested with success.
WITHDRAW_SUCCESS 6 The withdrawal has been executed with success.
INVALID_AMOUNT -1 The amount of the operation is invalid (lower than or equal to 0), it will not be processed.
TRANSFER_VENDOR_DISABLED -5 Payments for this vendor are disabled on Mirakl back-office, the transfer is blocked.
WITHDRAW_VENDOR_DISABLED -6 The vendor is disabled on Mirakl back-office, the withdraw is blocked.
WITHDRAW_FAILED -7 The withdrawal has been executed and failed.
WITHDRAW_CANCELED -8 The withdrawal has been canceled.
TRANSFER_FAILED -9 The transfer has been executed and failed.
TRANSFER_NEGATIVE -10 The transfer has not been executed because there are not enough funds in the HiPay technical account.
WITHDRAW_NEGATIVE -11 The withdrawal has not been executed because there are not enough funds in the wallet account.
WITHDRAW_PAYMENT_BLOCKED -12 Payments for this vendor are disabled on Mirakl back-office, the withdraw is blocked.