User Tools

Site Tools


emoneyoperations

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

emoneyoperations [2015/03/13 14:04]
emoneyoperations [2015/03/13 14:04] (current)
Line 1: Line 1:
 +====== 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 =====
 +[[https://​secure.moneypolo.com/​emoney_operations/​process.php]]
 +
 +\\ \\
 +===== 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 |
 +| <​del>​Egopay (EP)</​del>​ | - |
 +| <​del>​Liberty Reserve (LR)</​del>​ | - |
 +| <​del>​Moneybookers (MB)</​del>​ | - |
 +
 +\\ \\
 +===== Operating algorythm =====
 +  - 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).
 +  - The merchant system redirects the user to the pre-determined service page, which specifies all the payment options and pages with successful/​error payments.
 +  - Service determines payment system the payment is related to and redirects the user to the appropriate billing portal.
 +  - User processes payment (if payment system supports asynchronous notifications,​ during the registration,​ the payment system communicates with a service without any user activity).
 +  - 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:
 +{{ ::​emoney-scheme.png?​500 |}}
 +
 +  - User requests a form for depositing to an account with Emoney. ​
 +  - The merchant system prepares all parameters for sending. (If necessary, iteration 1 - 2 may be repeated several times) ​
 +  - User sends the predetermined form to the service address. ​
 +  - The service processes the incoming request and redirects user to the payment portal of the corresponding system. ​
 +  - 
 +    - In the process of payment the system sends requests to the service for payment confirmation (no user interaction required). ​
 +    - If the merchant system specifies the address of notification page, the service translates these requests to the merchant system as well. 
 +  - * 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. ​
 +  - Payment system redirects the user back to the service address. ​
 +  - 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 ([[EmoneyOperations#​Systems and currencies the service works with|section 2]]) |
 +| Amount | decimal | Amount |
 +| Currency| string | Currency ([[EmoneyOperations#​Systems and currencies the service works with|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) |
 +|HASH|string|Request 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:
 +<code php>
 +$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));
 +</​code>​
 +\\ \\
 +
 +==== 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 ([[EmoneyOperations#​Systems and currencies the service works with|section 2]]) |
 +| MerchantDocID| string | Merchant document ID |
 +| Amount | decimal | Amount |
 +| MerchantFee | decimal | Fee amount |
 +| MerchantAmount | decimal | Merchant amount (Amount - MerchantFee) |
 +| Currency| string | Currency ([[EmoneyOperations#​Systems and currencies the service works with|section 2]]) |
 +| ResponseData| string | all data received from the payment system of the following form **key1=value1::​ ... ::​keyN=valueN**|
 +|HASH|string|Request 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:
 +<code php>
 +$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));
 +</​code>​
 +
 +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 =====
 +
 +  - Get merchant code from the MayzusFS company and test key for request signs.
 +  - Implement the following pages on the merchant website:
 +    - Send payment (the form preparing and sending data to the MayzusFS service page)
 +    - Successful transactions page
 +    - Failure and error page 
 +    - Page for processing intermediate requests (**is optional, but the MayzusFS company recommends that you always process payments this way**)
 +  - Test payments together with MayzusFS support specialists.
 +  - 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)