User Tools

Site Tools


securepayment.simpleform

Secure Payment 2.0 - SimpleForm



Definitions

  • User - the user of the merchant system
  • Merchant system – user accounting merchant system that allows to deposit funds to the account or pay for the products/services via MayzusFS account.
  • Service - MayzusFS service, enabling processing of merchant system requests when dealing with payment.
  • S2S message – Server to Server message without user interaction via secured channel (HTTPS POST).



Before start

To start integration Merchant need to provide URL on his website.

  • S2S URL - secure page where Service will check transactions and send notification about successful transaction.



Service address

http://testpayment.moneypolo.com/process.simple.php

Please note, that test and prod keys are different from each other. Working key will be issued by MoneyPolo company at the end of the testing period.

Operating algorythm

  1. The user logins to the merchant system and select MayzusFS as payment option (User must have an account in MayzusFS system already).
  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 show user transaction summary and options to complete payment. User can cancel the transaction by pressing cancel button, whenever he/she decide to.
  4. After user press confirm button Service send unsigned S2S message of type „CHECK“, that contains all transaction data. Service expects string 'OK' as response, otherwise Service consider this check as unsuccessfull, cancel transaction and redirects user back to fail page.
  5. If S2S check is successfull, user can continue with payment process. Service process payment and after successfull transaction execution send signed S2S message of type „COMPLETED“, that contains all transaction data. Service expects string 'OK' as response to this message, otherwise message is undelivered, but transaction is finished, no matter to S2S notification.
  6. If user choose SOFORT payment after message “CHECK” you will receive signed S2S message of type “PENDING”. Service expects string 'OK' as response to this message. It means that payment was processed but money is not credited to the merchant account
  7. The user immediately redirected to the appropriate page of the merchant system.
  8. If transaction is in test mode (parameter TestMode = 1), everything is exactly the same, except in step 5, where transaction will not be executed at all. Some payment options will not be available in test mode.
  9. In case of refund our Service will send signed S2S message of type “REFUND” in SPStatus parametr, that contains all transaction data. Service expects string 'OK' as response to this message. In case the action was unsuccessful the service will automatically resend it with the certain periodicity.



Parameters description

The list of request parameters that the merchant system should send to the Service for processing.

Name Type Description
MerchantCode string Merchant code (issued by the MayzusFS company at the beginning of integration)
Data string JSON encoded array of parameters. see below
Signature string Request signature

Signature is a string received from encrypting merchant code, json-encoded transaction data and the merchant secret key using SHA512 method.
Pseudo code for receiving sign:
HASH = UPPERCASE ( SHA512 ( MERCHANTCODE + JSONDATA + SECRET_KEY))

Example of outbound request sign implementation in PHP language:

<?php
$SecretKey = '0123456789876543210';
 
$MerchantCode = 'YOUR CODE HERE';
$Signature = '';
$DataArray = array();
 
$DataArray['SPFirstName'] = 'CLIENT FIRSTNAME';
$DataArray['SPLastName'] = 'CLIENT LASTNAME';
$DataArray['SPAddressLine1'] = 'CLIENT ADDRESS';
$DataArray['SPAddressLine2'] = '';
$DataArray['SPCity'] = 'CLIENT CITY';
$DataArray['SPState'] = 'CLIENT STATE';
$DataArray['SPCountryCode'] = 'CLIENT COUNTRY CODE';
$DataArray['SPPostalCode'] = 'CLIENT ZIP';
$DataArray['SPEmail'] = 'CLIENT EMAIL';
$DataArray['SPMobile'] = 'CLIENT PHONE';
$DataArray['SPBirthDate'] = 'CLIENT BDAY';
 
$DataArray['SPAmount'] = 'YOUR AMOUNT';
$DataArray['SPCurrency'] = 'YOUR CURRENCY';
$DataArray['SPDetails'] = 'YOUR DETAILS';
$DataArray['SPTestMode'] = '1';
$DataArray['SPMerchantTransactionID'] = 'YOUR INTERNAL TRANSACTION IDENTIFICATOR';
$DataArray['SPSuccessURL'] = 'http://localhost/success';
$DataArray['SPFailURL'] = 'http://localhost/fail';
 
$Data = json_encode($DataArray);
 
var_dump($Data);
 
/* now $Data is string like this:
{"SPFirstName":"CLIENT FIRSTNAME","SPLastName":"CLIENT LASTNAME","SPAddressLine1":"CLIENT ADDRESS","SPAddressLine2":"","SPCity":"CLIENT CITY","SPState":"CLIENT STATE","SPCountryCode":"CLIENT COUNTRY CODE","SPPostalCode":"CLIENT ZIP","SPEmail":"CLIENT EMAIL","SPMobile":"CLIENT PHONE","SPBirthDate":"CLIENT BDAY","SPAmount":"YOUR AMOUNT","SPCurrency":"YOUR CURRENCY","SPDetails":"YOUR DETAILS","SPTestMode":"1","SPMerchantTransactionID":"YOUR INTERNAL TRANSACTION IDENTIFICATOR","SPSuccessURL":"http:\/\/localhost\/success","SPFailURL":"http:\/\/localhost\/fail"}
*/
 
$sep = '##';
$str = $sep . $MerchantCode;
$str .= $sep . $Data;
$str .= $sep . $SecretKey;
$str .= $sep;
 
$Signature = strtoupper(hash('sha512', $str));



Request JSON data object description

Name Type Description
SPFirstName string [A-Za-z0-9_\-\.,;:\\\@\/#\$%\&\*\(\)\[\] ]{1,150}
SPLastName string [A-Za-z0-9_\-\.,;:\\\@\/#\$%\&\*\(\)\[\] ]{1,150}
SPAddressLine1 string [A-Za-z0-9_\-\.,;:\\\@\/#\$%\&\*\(\)\[\] ]{1,50}
SPAddressLine2 string [A-Za-z0-9_\-\.,;:\\\@\/#\$%\&\*\(\)\[\] ]{0,50} *optional
SPCity string [A-Za-z0-9_\-\.,;:\\\@\/#\$%\&\*\(\)\[\] ]{1,50}
SPState string [A-Za-z0-9_\-\.,;:\\\@\/#\$%\&\*\(\)\[\] ]{0,50} optional
SPCountryCode string [A-Z]{2}
SPPostalCode string [a-zA-Z0-9 ]{0,50}
SPEmail string [A-Za-z0-9_\-\.@\+]{1,100}
SPMobile string +[0-9]{1,20} in international format +xxxxxxxx…
PSBirthDate string [0-9]{4}-[0-9]{2}-[0-9]{2} *optional
SPAmount decimal Amount
SPCurrency string Currency char(3) ISO code. (USD/EUR/..)
SPMerchantTransactionID string Unique ID of operation in merchant's system. Purpose is to connect transaction in merchant's system with transaction in MoneyPolo system.
SPDetails string Details of payment
SPTestMode int Test mode indicator 0/1 (On test environment, use always 0)
SPSuccessURL string Success redirect URL
SPFailURL string Fail redirect URL (ErrorCode and ErrorMessage variable will be passed as well)
SPPaymentMethod string * optional. code of preferred payment method. CC / WIRE / EMONEY
SPLang string EN/RU language code of interface
SPPaymentProvider string * optional. code of preferred payment provider. EMONEY only. BP (BTC) / OK (Okpay) / QW (QiWi) / SF (Sofort). if defined, customer will be redirected directly to selected payment gateway

The list of request parameters that the Service will sent to the merchant system in S2S message. Signature parameter appears only for COMPLETED type of S2S message.

Name Type Description
MerchantCode string Merchant code (as in request)
Data string JSON encoded array of parameters. see below
Signature string Response signature. only for COMPLETED type

S2S JSON data object description

SPAmount decimal Amount
SPCurrency string Currency char(3) ISO code - USD/EUR
SPMerchantTransactionID string Merchant operation ID
SPDetails string Details of payment
SPTestMode int Test mode indicator 0/1
SPStatus stringStatus of the transaction after processing
SPID intID of operation in MoneyPolo
SPAccountNumber stringMoneyPolo account number
SPAccountName stringMoneyPolo account name

Signature is a string received the same way as for request, from encrypting merchant code, json-encoded transaction data and the merchant secret key using SHA512 method.
Pseudo code for receiving sign:
HASH = UPPERCASE ( SHA512 ( MERCHANTCODE + JSONDATA + SECRET_KEY))

Example of checking signed S2S request implementation in PHP language:

$SecretKey = '0123456789876543210';
 
$sep = '##';
$str = $sep . $_POST['MerchantCode'];
$str .= $sep . $_POST['Data'];
$str .= $sep . $SecretKey;
$str .= $sep;
 
$Signature = strtoupper(hash('sha512', $str));
 
$hash = strtoupper(hash('sha512', $str));
 
if ($hash != strtoupper($_POST['Signature']))
{ 
  exit('failed to check transaction data. Possible hacking attempt'); 
}



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)
    2. Successful transactions page
    3. Failure and error page
    4. page for processing S2S requests (its the only page where you can believe to transaction data – no user interaction. The only place to pefrom credit/debit operations on merchant system)
  3. Test payments together with MoneyPolo support specialists using test card number: 5444870724493746 or 4012001037141112.
  4. After all the successful tests, switch the system to the operation mode.



Error codes

Error code Description
101 Missing request data
102 Unable to load merchant data
103 Merchant can not process transactions
104 Wrong signature
105 Internal error. Transaction is logged for further analysis
106 Error checking transaction (S2S)
107 Error creating signature (S2S)
108 Error processing transaction
109 Transaction cancelled by user
110 Duplicate payment
securepayment.simpleform.txt · Last modified: 2016/09/26 14:53 by Anatolii Zhiliaev