User Tools

Site Tools


securecardpayment

This is an old revision of the document!


Secure Card Payment



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.
  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. The user immediately redirected to the appropriate page of the merchant system.
  7. 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.
  8. 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['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","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)
SPSuccessURL string Success redirect URL
SPFailURL string Fail redirect URL (ErrorCode and ErrorMessage variable will be passed as well)
SPClientFirstName string * optional.
SPClientLastName string * optional.
SPClientBirthDate string * optional. YYYY-MM-DD
SPClientCountry string * optional. char(2)
SPClientCity string * optional.
SPClientPostalCode string * optional.
SPClientAddress string * optional.
SPClientStateCode string * optional.
SPClientEmail string * optional.
SPClientPhone string * optional.
SPDynamicDescriptor string * optional.
SPLang string * optional. EN/RU language code of interface
SPShowClientDetails int * optional. 0/1 where 1 is to force client to fill up his personal data

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

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
securecardpayment.1466766851.txt.gz · Last modified: 2016/06/24 12:14 by Dmitry Karpenko