Hosted payment pages - Accepting crypto

• Overview
• HPP integration flow
  • General settings
  • Create product
  • Payment methods
  • Available coins
  • Coins configuration
• Payment form
  • Pop-up payment form
  • iFrame payment form
  • Redirect payment form
• Callback 2.0
• The locale for the payment page
• Custom Product API
• Appearance
• Maxpay.js
• Signature calculation
• Checksum calculation
• Test mode
• Going to live

Overview

Now you can easily accept cryptocurrencies and stablecoins on various blockchains. This guide will cover some basics of setting up your account, receiving payments, and using your account.

HPP integration flow

To get started with receiving the payments using Maxpay hosted payment pages you need to:

1. Sign up at my.maxpay.com.

2. Create an application in the Payment pages section;

3. In the General section fill up the main data with valid information;

4. Create product at section Product to sell or use the Custom Product API (information provided below);

5. Contact support to add Crypto payment in the Payment Methods section (support@maxpay.com)

6. The next step is to turn on crypto in the Payment Methods section;

7. The final setting is a customization of the payment widget in the Payment for section;

8. Test your payment widget: check that redirect URLs work correctly and callback data is received.

9. When everything is done - send an application to the Maxpay Team for review.

General settings

Fill up the fields:

Create product

You can sell goods using Maxpay payment flow or send us the custom products using custom product API. In the section Products to sell you can create a fixed, trial, or subscription product. Please note that only fixed products can be sold via cryptocurrencies. Please, use our Guide in the Merchant portal with detailed steps of creation.

Payment methods

Here you can manage payment methods available on your payment widget. Just turn on the toggle button for activation. To preselect a crypto payment method on your payment page - add to the payment widget code the "payment_method" parameter:

Available coins

Coins configuration

Any coin and blockchain from the list could be added to the HPP. Also, it is possible to set up the order of coins on the HPP. Contact support for configuration.

Payment form

Maxpay’s payment form customizer allows you to:

1. Edit css of the widget - simply change css and hit the save button;

2. Upload your logo - the logo must be at least 170px by 70px and smaller than 512KB;

3. Choose Pop up, iFrame, or Redirect solution.

Pop Up payment form

Example of the pop-up payment form:

<div> <form class='pspPaymentForm'> <script src="https://hpp.maxpay.com/paymentPage.js" class="pspScript" data-iframesrc="https://hpp.maxpay.com/hpp" data-buttontext="Pay!" data-name="Application" data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9" data-signature="199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc4 8e3981f87" data-uniqueuserid="user123" data-payment_method='Crypto payments' data-uniqueTransactionId='transactionId123' data-productPublicId='productId120' data-email='john.doe@gmail.com' data-firstname='John' data-lastname='Doe' data-phone='1800080048' data-address='Address 123' data-city='New York' data-country='USA' data-zip='12100' data-success_url='https://merchant.com/successful-purchase' data-decline_url='https://merchant.com/unsuccessful-purchase' data-backUrl='https://merchant.com' data-locale='en-US' data-displaybuybutton="true" data-type="popup"> </script> </form> </div>

Parameters of the Pop Up payment form

If the merchant sends additional parameters to the payment form, then a signature value should be calculated, instead of using a default value. Use additional parameters for sending them to Pop Up payment form:

iFrame payment form

Example of iFrame payment form:

<div> <script src="https://hpp.maxpay.com/paymentPage.js" class="pspScript" data-iframesrc="https://hpp.maxpay.com/hpp" data-buttontext="Pay!" data-name="Application" data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9" data-signature="199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc4 8e3981f87" data-uniqueuserid="user123" data-payment_method='Crypto payments' data-uniqueTransactionId='transactionId123' data-productPublicId='productId120' data-email='john.doe@gmail.com' data-firstname='John' data-lastname='Doe' data-phone='1800080048' data-address='Address 123' data-city='New York' data-country='USA' data-zip='12100' data-success_url='https://merchant.com/successful-purchase' data-decline_url='https://merchant.com/unsuccessful-purchase' data-backUrl='https://merchant.com' data-locale='en-US' data-type="integrated" data-width="auto" data-height="auto"> </script> <form class='pspPaymentForm'></form> <iframe id='psp-hpp-199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87'></iframe> </div>

Parameters for iFrame payment form

If the merchant sends additional parameters to the payment form, then a signature value should be calculated, instead of using a default value. Use additional parameters for sending them to the iFrame payment form:

Redirect payment form

Example of Redirect form:

<form action='https://hpp.maxpay.com/hpp' class='redirect_form' method='post'> <input type='hidden' name='key' value='pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9'> <input type='hidden' name='signature' value='199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87 '> <input type='hidden' name='uniqueuserid' value='user123'> <input type='hidden' name='payment_method' value='Crypto payments'> <input type='hidden' name='uniqueTransactionId' value='transactionId123'> <input type='hidden' name='productPublicId' value='productId120'> <input type='hidden' name='email' value='john.doe@gmail.com'> <input type='hidden' name='firstname' value='John'> <input type='hidden' name='lastname' value='Doe'> <input type='hidden' name='phone' value='1800080048'> <input type='hidden' name='address' value='Address 123'><input type='hidden' name='city' value='New York'> <input type='hidden' name='country' value='USA'> <input type='hidden' name='zip' value='12100'> <input type='hidden' name='success_url' value='https://merchant.com/successful-purchase'> <input type='hidden' name='decline_url' value='https://merchant.com/unsuccessful-purchase'> <input type='hidden' name='backUrl' value='https://merchant.com'> <input type='hidden' name='locale' value='en-US'> <button type='submit'>Pay</button> </form>

Parameters of Redirect form

If the merchant sends additional parameters to the payment page, then a signature value should be calculated, instead of using a default value. Use additional parameters for sending them to the Redirect payment form:

Callback 2.0

It is important to know, that neither Maxpay nor cryptoproccessor can control the amount that will be sent by the customer, as the customer is the one to initiate the payment and decide which amount will be sent. So it is crucial to have a validation on the merchant side if the whole amount has been received, before the product shipment or service to be provided.

Also, the transfer could be made in a few payments. In this case, you will receive callbacks per each transfer. The idempotency can be checked based on reference. It would be different per each payment.

Please note, that redirecting to success_url is not a guarantee that the payment was completed in the full amount. Callbacks could be received even after the customer is redirected.

Example of the callback 2.0 request to the merchant in application/JSON format:

{ "status": "success", "code": 0, "message": "Transaction processed successfully", "uniqueTransactionId": "crpt240621121135m858a203u7ec7badc4a6da51", "reference": "CSHFF00001CFD4C1F", "uniqueUserId": "auto_41cAYUx4zgUjnOK4", "clientAmount": 15.9, "clientCurrency": "EUR", "processedAmount": 0.00486086, "processedCurrency": "ETH", "transactionType": "SALE", "productList": [ { "productId": "p_3c47664025", "name": "Gravicapa", "amount": 15.9, "currency": "EUR" } ], "testMode": "0", "processedAlgorithm": "Sepolia", "processedRate": 0.0003057145, "walletAddress": "0xC9699c3234e2194De016A601D8d321BB65f67c01", "walletTag": "" } 

Callback purpose: callback is a notification by Maxpay regarding a transaction status. HTTPS is required for the callback URL.

Description of the callback parameters:

Maxpay sends callback 2.0 data to the merchant in application/JSON format. The callback is received by a merchant when in response Maxpay gets the code - 200 (it’s required), and body text - OK (it’s optional). In other cases, callback is not received and Maxpay will try periodically to re-send callback data. The number of attempts are limited. Be advised, that transaction status is better to handle by transaction code, not status or text message.

For signature calculation, you should take sha256 from the callback string.

The locale for the payment page

Maxpay provides different languages for the payment page.

Look at the available languages below:

Let's look at the sample with a French locale.

Custom product API

In case you would like to make the product selection on your side you have a possibility to pass custom products and avoid the ‘create product’ step on Maxpay’s side. "To make this happen simply send the POST request with the “customproduct” parameter. This parameter should contain a valid array of products.

Parameters for custom fixed crypto products are provided below:

If you wish to request a custom product in fiat replace coin with any supported valid ISO-3 currency. Example of a custom product for 1 USD:

Appearance

Crypto as an additional payment method

Cryptocurrencies can be used along with other solutions that Maxpay offers, such as card processing, and ApplePay. In this case, all of the payment methods should be enabled in MPortal and a HPP:

As a result, your customer will be able to choose between various payment methods on HPP including crypto:

In case the customer clicks the “PAY WITH CRYPTO” button, he will be redirected to crypto HPP. Please refer to the next section

The customer wants to pay with crypto and selects it on HPP

In case the customer wants to pay with crypto he will have the ability to choose between configured cryptocurrencies, stablecoins, and blockchains. In this case, the total amount in the selected cryptocurrency will be calculated based on the market average exchange rate at the moment of the selection. The exchange rate will be returned in the Callback 2.0.

The customer wants to pay with crypto and selects it on the merchant side

If you would like to rely on your own exchange rate you could build the process of currencies selection and amount calculation on your side. Then Custom product API could be used to process the transaction based on the currency selected and the amount. In the example below the merchant has decided that 1 ETH should be charged to a client. The amount can’t be changed and other currencies are not available even though they are configured

Maxpay.js

The functions below will help you to manipulate the javascript of the payment page and the products created on Maxpay's side:

Maxpay.showProductList() - the full list of products;

Maxpay.sellProduct("PUBLIC_ID") - display payment form for the specific product created in the Maxpay merchant portal. The "PUBLIC_ID" can be found in the product creation section of the application settings in the Maxpay merchant portal. *If you pass the wrong or empty "PUBLIC_ID" the payment page will display the full list of products.

Maxpay.close() - close pop-up or an iFrame.

HPP signature calculation

When you use Custom product API or additional parameters the process of creating a signature can be resolved in a few ways:

1) Using the Maxpay GitHub library, which allows you to shape integration code with different parameters and not think about the signature because the library can sign the whole form itself.

2) If you would like to calculate the value of a payment form signature by your own, use the description of the algorithm below:

Sample form for signature calculation

<form method="post" action="https://hpp.maxpay.com/hpp"> <input type='hidden' name="key" value="pkTest_c4tgzRjQBO4Fa4d7f2OoJkIutFMGiCCC"> 

<input type='hidden' name="customproduct" value="[{'productId':'1','productType':'fixedProduct','productName':'Product name','currency':'USD','amount':100}]">

<input type='hidden' name="signature" value="put_a_signature_value_here">

<input type='submit' name="Pay" value="Pay"> </form>

The algorithm is provided below:

Form a line according to the principle: key1 = value1|key2 = value2|switchN = valueN|your_privat_key your keys should be sorted ascending

The final line is converted into the lowercase, and then take hash( 'sha256', 'resulting') from the line you have;

Example of the signature calculation based on the form above:

 <?php
//key- it's Public key from merchant portal (my.maxpay.com-> Payment pages-> General->
API keys).
//The last parameter is Private key from merchant portal (my.maxpay.com-> Payment pages-> General-> API keys).
$resulting =
strtolower('customproduct=[{"productId":"12345","productType":"fixedProduct","productName
":"Product
name","currency":"usd","amount":100}]|key=pkTest_c4tgzRjQBO4Fa4d7f2OoJkIutFMGiCCC
|skTest_aKuKHhan1arfwrYBXSUja46ax4qrA111');
$signature = hash("sha256", $resulting);
?>

When a signature value is calculated just put this value into html form and run the code. If the form doesn't open it means that the value is not correct.

Also, take a look at our sample on GitHub. This sample uses the class SignatureHelper. The full logic is available at the link GitHub sample code

CheckSum calculation for callback 2.0

PHP algorithm below shows the calculation logic of “checkSum”:

<?php
// Take callback body as a string
$data =
'{"uniqueTransactionId":"hpp121122113557m37186a23056u052f94975853","reference":"SLF
F0000000CAA2A73AS","uniqueUserId":"user123","totalAmount":100,"currency":"USD","tran
sactionType":"SALE","status":"success","message":"Transaction processed
successfully","code":0,"productList":[{"productId":"Product123","name":"DEMO","amount":10
0,"currency":"USD"}],"testMode":"1"}'.'skLive_e7vSTkUv7dZJOf97ppasdWe34rCK2ElVb';


// Count hash
echo $result = hash('sha256', $data);


?>

A callback body should be taken as a string and a private key should be added at the end of the string.

Count a value by the formula: hash('sha256', $data) where $data is a callback body string with the private key.

The counted value should be equal X-Signature value from the callback header.

Test mode

Before you go live, the Maxpay team should make sure that your flow works good. Influencing factors on switching from test mode to live mode: 1. Rendering payment form. 2. Callback handling.

To reproduce a declined status of the transaction, please, input an error code to the product name parameter. For Custom product API paste the 3100 error code or other from the response list into the "productName" parameter, it should be "productName":"3100". If the product is set up in the Merchant portal make changes in the Products to Sell section.

Going to live

In order to switch the processing to live mode simply send us your integration for review by clicking on the ‘send for review’ button in your ‘application’ section. After that, you should provide a value of the live callback URL:

1. Click on the button "Account settings" (upper-right corner of the merchant portal).

2. Select the "Firewall" section.

3. Click on the button "Send new request".

4. Input a callback URL value in the "The callback URL" string.

5. Click on the button "Save".

6. The production callback URL should be whitelisted on the Maxpay side. Necessarily with HTTP protocol, SSL generated by yourself is not valid. Our Integration Team will review your application carefully and get back to you as soon as possible.