CloudPayments Integration on Custom Website: Complete Guide

CloudPayments Integration with Custom Website in Russia

CloudPayments integrates with custom websites in Russia through API key configuration and implementation of an instant payment notification (IPN) handler. The main challenges arise from the lack of practical examples in the official documentation, but the functionality is accessible through GitHub repositories and guides from other developers.

Table of Contents

• Official Documentation and Resources
• Setting up IPN (Instant Payment Notifications)
• Code Examples for Integration
• t-kassa Integration
• Solving Common Problems
• Security Best Practices

Official Documentation and Resources

The primary source of information is the official CloudPayments developer documentation. Although it only lists API functions, this is the basic resource for understanding the interaction structure.

Key elements for integration:

• Public ID - public identifier of your account
• API Password - secret key for signing requests
• URL for IPN notifications - address of your server for processing payments

For a custom website, you need to create a payment handler that will:

1. Accept notifications from CloudPayments
2. Verify the authenticity of requests
3. Update the order status in your system
4. Send confirmation of successful processing

Important: In the CloudPayments personal account, you need to specify the address for Payment notifications in the format http://your-site/handler.php with the POST method and Windows-1251 encoding, as specified in the PHPShop documentation.

Setting up IPN (Instant Payment Notifications)

IPN notifications are a critical component of integration, as it is through them that you receive information about payment statuses.

Main steps for IPN setup:

1. Create a handler on your server (for example, ipn_handler.php)

2. Configure receiving POST requests from CloudPayments

3. Implement HMAC signature verification for security

4. Process different payment statuses:

   • Success (successful payment)
   • Fail (failed payment)
   • Partial (partial payment)

Basic example of an IPN handler structure in PHP:

<?php
// Get data from CloudPayments
$rawData = file_get_contents('php://input');
$notificationData = json_decode($rawData, true);

// Verify HMAC signature
$publicId = 'your_public_id';
$apiKey = 'your_api_key';
$receivedSignature = $_SERVER['HTTP_AUTHORIZATION'] ?? '';

// Calculate our signature
$calculatedSignature = base64_encode(hash_hmac('sha256', $rawData, $apiKey, true));

if ($receivedSignature === 'Basic ' . $calculatedSignature) {
    // Signature is valid, process the notification
    $invoiceId = $notificationData['InvoiceId'] ?? '';
    $amount = $notificationData['Amount'] ?? 0;
    $status = $notificationData['Status'] ?? '';
    
    // Update order status in your system
    updateOrderStatus($invoiceId, $status);
    
    // Send confirmation
    http_response_code(200);
    echo json_encode(['Success' => true]);
} else {
    // Invalid signature, ignore the request
    http_response_code(403);
    echo json_encode(['Error' => 'Invalid signature']);
}

Code Examples for Integration

JavaScript/Node.js Example

From the GitHub repository, there’s a Node.js example:

import {createServer} from 'http';
import {ClientService, TaxationSystem, ResponseCodes} from 'cloudpayments';

const client = new ClientService({
    privateKey: 'private key',
    publicId: 'public id',
    org: {
        taxationSystem: TaxationSystem.GENERAL,
        inn: 123456789
    }
});

const handlers = client.getNotificationHandlers();
const server = createServer(async (req, res) => {
    if (req.url == '/cloudpayments/fail') {
        const response = await handlers.handleFailRequest(req, async (request) => {
            // Process information about failed payment
            return ResponseCodes.SUCCESS;
        });
        res.setHeader('Content-Type', 'application/json');
        res.end(JSON.stringify(response));
    }
});

server.listen(3000, () => {
    console.log('Server running on port 3000');
});

PHP Client Library

The official CloudPayments PHP library provides a convenient interface for working with the API:

<?php
require_once 'vendor/autoload.php';

use CloudPayments\Manager;
use CloudPayments\Model\Request\Payment\Card;

$manager = new Manager(
    'your_public_id',
    'your_api_password'
);

// Creating a payment
$response = $manager->paymentCards()->post([
    'Amount' => 10.00,
    'Currency' => 'RUB',
    'IpAddress' => '192.168.0.1',
    'Name' => 'Ivan Ivanov',
    'CardCryptogramPacket' => 'eyJoYXNoIjoiNDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0IiwiaHR0cHM6Ly9hdXRoLmNsb3VkYXBwbGVzLmNvbS9hcGkvY2FyZHMvY2FyZHMtcGF5bWVudC8iLCJ0eXBlIjoiUEFTU1dPUkQiLCJ2ZXJzaW9uIjoxfQ==',
    'Description' => 'Payment for product #123',
    'InvoiceId' => 'ORDER-123',
    'Email' => 'customer@example.com'
]);

WordPress Integration

From the Misha Agency guide, there’s an example for WordPress:

<?php
// File 3ds.php for processing 3DS authentication
$publicID = 'PUBLIC_API_KEY';
$apiKey = 'SECRET_API_KEY';

// Process payment after entering confirmation code
$response = wp_remote_post('https://api.cloudpayments.ru/payments/cards/post3ds', array(
    'method' => 'POST',
    'timeout' => 45,
    'headers' => array(
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
        'Authorization' => 'Basic ' . base64_encode($publicID . ':' . $apiKey)
    ),
    'body' => json_encode($paymentData)
));

t-kassa Integration

t-kassa is a simplified version of CloudPayments with reduced functionality. Main differences:

1. Fewer settings - no complex tax system parameters
2. Simplified API - methods are more basic
3. Limited capabilities - some functions are not available

Typical problems when integrating t-kassa:

• Lack of comprehensive documentation
• Difficulties getting technical support
• Limited customization options for the payment form

If you need to use t-kassa, I recommend:

1. Start with integrating the full version of CloudPayments
2. If necessary, switch to t-kassa as a simpler alternative
3. Adapt the code to work with the simplified API

Solving Common Problems

Problem: No practical examples in documentation

Solution: Use the following resources:

• 1C-Bitrix CloudPayments module - studying the module’s source code
• Integration with Tilda - adapting examples for your system
• Webasyst guide - universal approaches to integration

Problem: HMAC verification doesn’t work

Solution: Make sure that:

1. The correct algorithm is used (SHA256)
2. The API key doesn’t contain extra spaces
3. The data for signing doesn’t change between calculation and verification

Problem: Notifications are not coming through

Solution:

1. Check if your IPN handler is accessible from the internet
2. Make sure your server correctly handles POST requests
3. Check CloudPayments logs for errors

Security Best Practices

1. Always verify HMAC signatures before processing notifications
2. Use HTTPS for all communications with your server
3. Store API keys in a secure location (not in Git repository)
4. Implement logging of all notifications for debugging
5. Restrict access to the IPN handler to CloudPayments IP addresses

Important: According to security recommendations, always use HTTPS to encrypt data between the payment gateway and your server, and implement HMAC signature verification for data integrity.

Sources

1. Official CloudPayments Developer Documentation
2. CloudPayments PHP Client Library on GitHub
3. Integration Example on JavaScript/Node.js
4. CloudPayments Integration Guide for PHPShop
5. CloudPayments Connection Guide for WordPress
6. Payment Module for 1C-Bitrix
7. CloudPayments Connection in Tilda
8. CloudPayments Integration with Webasyst

Conclusion

Integrating CloudPayments with a custom website in Russia requires time and attention to detail, but it’s fully achievable. Main recommendations:

1. Start by studying the official documentation and GitHub repositories
2. Implement a reliable IPN handler with HMAC signature verification
3. Test the integration in test mode before launching to production
4. Use ready-made code examples from various sources and adapt them to your needs
5. If you encounter difficulties with t-kassa, consider using the full version of CloudPayments

If you face unique problems during integration, I recommend contacting CloudPayments support or studying the source code of ready-made modules for various CMS, which may provide additional ideas for implementation.