User Tools

Site Tools


securepayment20

Secure Payment 2.0



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 MoneyPolo account.
  • Service - MoneyPolo 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

Operating algorythm

  1. The user logins to the merchant system and select MoneyPolo as payment option (User must have an account in MoneyPolo 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 MoneyPolo 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:

$SecretKey = '0123456789876543210';
 
$MerchantCode = 'YOUR CODE HERE';
$Signature = '';
$DataArray = array();
$DataArray['SPAmount'] = 'YOUR AMOUNT';
$DataArray['SPCurrency'] = 'YOUR CURRENCY';
$DataArray['SPDetails'] = 'YOUR DETAILS';
$DataArray['SPTestMode'] = '1';
$DataArray['SPMerchantTransactionID'] = 'YOUR INTERNAL TRANSACTION IDENTIFICATOR';
$DataArray['SPAccountID'] = 'MONEYPOLO ACCOUNT ID';
$DataArray['SPSuccessURL'] = 'http://localhost/success';
$DataArray['SPFailURL'] = 'http://localhost/fail';
 
$Data = json_encode($DataArray);
 
/* now $Data is string like this:
 {"SPAmount":"YOUR AMOUNT","SPCurrency":"YOUR CURRENCY","SPDetails":"YOUR DETAILS","SPTestMode":"1","SPMerchantTransactionID":"YOUR INTERNAL TRANSACTION IDENTIFICATOR","SPAccountID":"MONEYPOLO ACCOUNT ID","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));

and HTML form to pass prepared request to SecurePayment:

<html>
<head>
    <title>test process</title>
</head>
<body style="background-color: #fff;">
    <form id="dataForm" method="POST" action="http://testpayment.moneypolo.com/process.php">
		MerchantCode: <input name="MerchantCode" type="text" width="200" value="<?php echo $MerchantCode; ?>" /> <br/>
		Data: <input name="Data" type="text" width="200" value='<?php echo $Data; ?>' /> <br/>
		Signature: <input name="Signature" type="text" width="200" value="<?php echo $Signature; ?>" /> <br/>
		<input type="submit" value="Test process" />
    </form>
</body>
</html>



Request JSON data object description

Name Type Description
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)
SPAccountID int * optional (pass 0 in this case) MoneyPolo client account ID, who performs the payment
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. MP / CC / WIRE / EMONEY / MT
SPLang string * optional. EN/RU language code of interface
SPPaymentProvider string * optional. code of preferred payment provider. EMONEY only. BP/BH (BTC) / QW (QiWi) / SF (Sofort). if defined, customer will be redirected directly to selected payment gateway
SPUserVariable string * optional
SPPaymentType string * optional. additional param for few types. code of crypto currency in case of Crypto (BH). XBT/XBC/LTC/BTG/DSH/ETH

The list of request parameters that the Service will sent to the merchant system in S2S message. Signature parameter will not appear only for CHECK 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. not for CHECK 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 for MoneyPolo internal usage
SPAccountNumber stringMoneyPolo account number
SPAccountName stringMoneyPolo account name
SPUserVariable string
OperationType string code of payment type
DocumentID string Identifier of MoneyPolo operation
CardNumber string *for CC OperationType - masked card number
CreditedAmount decimal *for WIRE OperationType - amount credited in incoming payment
CreditedCurrency string *for WIRE OperationType - currency in incoming payment
OriginatorName string *for WIRE OperationType - originator name of incoming payment
FraudCheckResultstring *for CC OperationType
ThreeDSecureStatusstring *for CC OperationType
IssuerBankstring *for CC OperationType
IssuerBankCountrystring *for CC OperationType
ProviderErrorMessagestring *for CC OperationType
ProviderAcquirerErrorMessagestring *for CC OperationType
SecurityCheckResultstring *for CC OperationType
CreditedAmountstring *for EMONEY-BC OperationType
CreditedCurrencystring *for EMONEY-BC OperationType

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 . YOURMERCHANTCODE;
$str .= $sep . $_POST['Data'];
$str .= $sep . $SecretKey;
$str .= $sep;
 
 
$hash = strtoupper(hash('sha512', $str));
 
if ($hash != strtoupper($_POST['Signature']))
{ 
  exit('failed to check transaction data. Possible hacking attempt'); 
}
else
{
  // now signature is ok
  // it is on your conscience to check transaction data like currency/amount/etc
  echo 'OK';
}



Integration process

  1. Get merchant code from the MoneyPolo 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 MoneyPolo 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
111 Temporary unavailable
securepayment20.txt · Last modified: 2018/05/08 08:36 by Dmitry Karpenko