User Tools

Site Tools


emoneyoperations

Emoney Operations



Definitions

  • User - the user of the merchant system
  • Merchant system – user accounting merchant system that allows to deposit funds to the account.
  • Service - MayzusFS service, enabling centralized and universal processing of merchant system requests when dealing with payment systems on the Internet.
  • Payment system – one of the payment systems (WebMoney, Egopay, QIWI, etc).
  • EMoney purse – a purse in one of the payment systems.



Service address

Systems and currencies the service works with

System (code) Currencies
Webmoney (WM) WMZ, WME, WMR
OKPAY (OK) USD, EUR, GBP
QiWi (QW) USD, EUR
CashU (CU) USD
BitcoinPay (BP) USD, EUR, CZK, PLN
Egopay (EP) -
Liberty Reserve (LR) -
Moneybookers (MB) -



Operating algorythm

  1. The user logins to the merchant system and requests the page for depositing to an account with EMoney purse (assuming the user has already registered in the MayzusFS and an open account in it).
  2. The merchant system redirects the user to the pre-determined service page, which specifies all the payment options and pages with successful/error payments.
  3. Service determines payment system the payment is related to and redirects the user to the appropriate billing portal.
  4. User processes payment (if payment system supports asynchronous notifications, during the registration, the payment system communicates with a service without any user activity).
  5. The user returns to the page of the service, from which he is immediately redirected to the appropriate page of the merchant system.

Scheme of work:

  1. User requests a form for depositing to an account with Emoney.
  2. The merchant system prepares all parameters for sending. (If necessary, iteration 1 - 2 may be repeated several times)
  3. User sends the predetermined form to the service address.
  4. The service processes the incoming request and redirects user to the payment portal of the corresponding system.
    1. In the process of payment the system sends requests to the service for payment confirmation (no user interaction required).
    2. If the merchant system specifies the address of notification page, the service translates these requests to the merchant system as well.
  5. * If supported by the payment system, the service can check (“authorize”) service request of the payment system. Only after this step, the user can make payment.
  6. Payment system redirects the user back to the service address.
  7. Depending on whether the transaction was successful or not, the service redirects the user to the appropriate page of the merchant system.



Security

All communication between the service and the merchant system is carried out over a secure HTTP channel using POST method and is signed by key. The MayzusFS company issues a key for the merchant at the beginning of integration. When switching to the operating mode of the service the key is changed.



Message Format Description

Format of the payment request and its sign

The list of outbound request parameters that the merchant system should translate to the service for processing.

Name Type Description
Merchant_Code string Merchant code (issued by the MayzusFS company at the beginning of testing)
Account_ID int User account number in the MayzusFS, for which the transaction is being performed
RUID string Merchant user ID
EMoney_System_Code string Payment system code (section 2)
Amount decimal Amount
Currency string Currency (section 2)
Details string Additional text
MerchantDocID string Merchant document ID
Success_URL string URL to which the user will be redirected in case of successful transaction.
Fail_URL string URL to which the user will be redirected in case if payment fails.
Result_URL string URL to which the system’s intermediary request (if supported by the payment system) will be sent
UserVariable * string * Optional. Additional info required by some systems. (in case of QiWi - you must put client phone number into that variable in international format: +7923xxxxxxx)
HASHstringRequest signature

HASH is a string received from encrypting all data critical for the transaction and the merchant secret key using SHA512 method.

Pseudo code for receiving sign:
HASH = UPPERCASE ( SHA512 ( MERCHANT_CODE + ACCOUNT_ID + RUID + EMONEY_SYSTEM_CODE + AMOUNT + CURRENCY + DETAILS + MERCHANTDOCID + SUCCESS_URL + FAIL_URL + RESULT_URL + UserVariable + SECRET_KEY))
Example of outbound request sign implementation in PHP language:

$Secret_Key = '0123456789876543210';
$str = 'Merchant_Code';
$str .= 'Account_ID';
$str .= 'RUID';
$str .= 'EMoney_System_Code';
$str .= 'Amount';
$str .= 'Currency';
$str .= 'Details';
$str .= 'MerchantDocID';
$str .= 'Success_URL';
$str .= 'Fail_URL';
$str .= 'Result_URL';
$str .= 'UserVariable';
$str .= $Secret_Key;
$hash = strtoupper(hash('sha512', $str));



System response description and signature

All the service responses to the merchant system are transparent (any data received from the payment system are sent to the merchant system) with the addition of sign and extra fields identifying the transaction.


Name Type Description
All data received from the payment system
Merchant_Code string Merchant code as in request
EMoney_System_Code string Payment system code (section 2)
MerchantDocID string Merchant document ID
Amount decimal Amount
MerchantFee decimal Fee amount
MerchantAmount decimal Merchant amount (Amount - MerchantFee)
Currency string Currency (section 2)
ResponseData string all data received from the payment system of the following form key1=value1:: … ::keyN=valueN
HASHstringRequest signature

HASH is a string received from encrypting all data critical for the transaction and the merchant secret key using SHA512 method.
Pseudo code for receiving sign:
HASH = UPPERCASE ( SHA512 ( MERCHANT_CODE + EMONEY_SYSTEM_CODE + MERCHANTDOCID + AMOUNT + CURRENCY + RESPONSE_DATA + SECRET_KEY))
Example of outbound request sign implementation in PHP language:

$Secret_Key = '0123456789876543210';
$str = $_POST['Merchant_Code'];
$str .= $_POST['EMoney_System_Code'];
$str .= $_POST['MerchantDocID'];
$str .= $_POST['Amount'];
$str .= $_POST['Currency'];
$str .= $_POST['ResponseData'];
$str .= $Secret_Key;
$hash = strtoupper(hash('sha512', $str));

If the generated sign coincides with the sign in the HASH variable of the incoming request, the data weren't changed and the source is definitely the MayzusFS service.



Integration process

  1. Get merchant code from the MayzusFS company and test key for request signs.
  2. Implement the following pages on the merchant website:
    1. Send payment (the form preparing and sending data to the MayzusFS service page)
    2. Successful transactions page
    3. Failure and error page
    4. Page for processing intermediate requests (is optional, but the MayzusFS company recommends that you always process payments this way)
  3. Test payments together with MayzusFS support specialists.
  4. After all the successful tests, switch the system to the operation mode.



Error codes

Error code Description
101 Unknown EMoney System Code
102 Internal. ESystem object not found
103 Wrong signature
104 Incorrect data
105 Operation is not allowed for users with this verification level
106 Error in data
107 Unknown receiver
108 Invalid amount
emoneyoperations.txt · Last modified: 2015/03/13 14:04 (external edit)