Introduction

The CloudIPSP PHP SDK is an open source library through which your PHP application can easily interact with the API. That allows you to accept payment by Visa/MasterCard cards on your website. Simply generating payment url, token, form.

Installation

1. You can install via Composer.

1.Composer Install

composer require cloudipsp/php-sdk-v2

1. To install without composer, just download the latest release. Then include manual auto loader to your project.

2.Manual installation

<?php
require '/path-to-sdk/autoload.php';

Simple start

Minimal startup example:

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

\Cloudipsp\Configuration::setMerchantId(1396424);
\Cloudipsp\Configuration::setSecretKey('test');

$data = [
    'currency' => 'USD',
    'amount' => 1111
];
\Cloudipsp\Checkout::url($data)->toCheckout();

Minimal configuration:

• 'setMerchantId' - Checkout Merchant ID from provider merchant portal.
• 'setSecretKey' - Merchant secret key, if operation is credit you need to set 'setCreditKey'

Full configuration:

• 'setMerchantId' - Checkout Merchant ID from provider merchant portal.
• 'setSecretKey' - Merchant secret key.
• 'setCreditKey'- Merchant credit key.
• 'setApiVersion' - Set api protocol version. Allowed ['1.0', '2.0'].
• 'setApiUrl' - Set api endpoint.
• 'setRequestType' - Set request type. Allowed ['json', 'xml', 'form'].
• 'setHttpClient' - Set http client. Allowed HttpCurl, HttpGuzzle.

Checkout

Payment url (host-to-host)

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  $data = [
        'order_desc' => 'tests SDK',
        'currency' => 'USD',
        'amount' => 1000,
        'response_url' => 'http://site.com/responseurl',
        'server_callback_url' => 'http://site.com/callbackurl',
        'sender_email' => 'test@fondy.eu',
        'lang' => 'ru',
        'product_id' => 'some_product_id',
        'lifetime' => 36000,
        'merchant_data' => array(
            'custom_data1' => 'Some string',
            'custom_data2' => '00000000000',
            'custom_data3' => '3!@#$%^&(()_+?"}'
        )
    ];
  $url = \Cloudipsp\Checkout::url($data);
  $data = $url->getData();

(array) getData() — returns checkout url data.

(null) toCheckout() — redirect to checkout page.

Required request Parameters:

Parameters	Description
order_id	Order ID. Can be generated by SDK.
merchant_id	Merchant unique ID.
order_desc	Order description. Generated by merchant in UTF-8. Can be generated by SDK.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
amount	Order amount in cents without a separator.
currency	Order currency(USD, EUR, RUB and others).

Host-to-host API supports the following text formats:

• form
• xml
• json

All other parameters look in provider documentation.

Payment form

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  $data = [
        'order_desc' => 'tests SDK',
        'currency' => 'USD',
        'amount' => 1000,
        'merchant_data' => [
            'custom_data1' => 'Some string'
        ]
    ];
  $form = \Cloudipsp\Checkout::form($data);

(string) returns payment form as string.

Required request Parameters:

Parameters	Description
order_id	Order ID. Can be generated by SDK.
merchant_id	Merchant unique ID.
order_desc	Order description. Generated by merchant in UTF-8. Can be generated by SDK.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
amount	Order amount in cents without separator.
currency	Order currency(USD,EUR,RUB and others).

All other parameters look in provider documentation.

Payment token (host-to-host)

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  $data = [
        'order_desc' => 'tests SDK',
        'currency' => 'USD',
        'amount' => 1000,
        'response_url' => 'http://site.com/responseurl',
        'server_callback_url' => 'http://site.com/callbackurl',
        'sender_email' => 'test@fondy.eu',
        'lang' => 'ru',
        'product_id' => 'some_product_id',
        'lifetime' => 36000,
        'merchant_data' => array(
            'custom_data1' => 'Some string',
            'custom_data2' => '00000000000',
            'custom_data3' => '3!@#$%^&(()_+?"}'
        )
    ];
  $token = \Cloudipsp\Checkout::token($data);
  $data = $url->getData();

(array) getData() returns checkout token data.

Required request parameters:

Order

Status

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
    $dataToGetStatus = [
        'order_id' => '123'
    ];
    $orderStatus = \Cloudipsp\Order::status($dataToGetStatus);
    var_dump($orderStatus->getData());

(array) getData() — returns order info.

(bool) isApproved() — method to check if payment is successful.

Required request Parameters:

Parameters	Description
order_id	Order ID which is generated by merchant.
merchant_id	Merchant unique ID.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.

Host-to-host API supports the following text formats:

• form
• xml
• json

Response is always returned in request context in the same content-type. So if request is sent in JSON, response will be sent in JSON format too.

Transaction List

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
     $dataToGetList = [
        'order_id' => '1234'
     ];
     $listData = \Cloudipsp\Order::transactionList($dataToGetList);
     var_dump($listData->getData());

(array) getData() — returns transaction list by order.

(bool) isCapturedByList() — method to check if is captured transaction in the data

Required request Parameters:

Parameters	Description
order_id	Order ID which is generated by merchant.
merchant_id	Merchant unique ID.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.

Host-to-host API supports the following text formats:

• form
• xml
• json

Refund payment

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
    $dataToReverse = [
       'currency' => 'USD',
       'amount' => 100,
       'order_id' => '1234'
    ];
    $refundOrder = \Cloudipsp\Order::reverse($dataToReverse);
    var_dump($refundOrder->getData());

(array) getData() — returns refunded order info.

(bool) isReversed() — method to check if refund is success.

Required request Parameters:

Parameters	Description
order_id	Order ID which is generated by merchant.
merchant_id	Merchant unique ID.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
currency	Order currency(USD,EUR,RUB and others).
amount	Order amount in cents without separator.

Host-to-host API supports the following text formats:

• form
• xml
• json

Capture order

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
     $dataToCapture = [
        'currency' => 'USD',
        'amount'   => 1000,
        'order_id' => '1234'
     ];
     $captureOrder = \Cloudipsp\Order::capture($dataToCapture);
     var_dump($captureOrder->getData());

(array) getData() — returns captured order info.

(bool) isCaptured() — method to check if capture request is true

Required request Parameters:

Parameters	Description
order_id	Order ID which is generated by merchant.
merchant_id	Merchant unique ID.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
currency	Order currency(USD,EUR,RUB and others).
amount	Order amount in cents without separator.

Host-to-host API supports the following text formats:

• form
• xml
• json

Get Atol logs

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
     $data = [
        'order_id' => '1234'
     ];
     $logs = \Cloudipsp\Order::atolLogs($data);
     var_dump($logs->getData());

(array) getData() — returns atol logs array.

Required request Parameters:

Parameters	Description
order_id	Order ID which is generated by merchant.
merchant_id	Merchant unique ID.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.

Host-to-host API supports the following text formats:

• json

Settlement

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  $data = [
      'currency' => 'USD',
      'amount' => 1000, // convert to 10.00$
      'order_desc' => 'tests SDK',
  ];
  $receiver = [
      [
          'requisites' => [
              'amount' => 500,
              'merchant_id' => 600001
          ],
          'type' => 'merchant'
      ],
      [
          'requisites' => [
              'amount' => 500,
              'merchant_id' => 700001
          ],
          'type' => 'merchant'
      ]
  ];
  $data['receiver'] = $receiver;

(array) getData() — returns response data.

Required request parameters:

Parameters	Description
order_id	Order ID. Can be generated by SDK.
merchant_id	Merchant unique ID.
order_desc	Order description. Generated by merchant in UTF-8. Can be generated by SDK.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
amount	Order amount in cents without separator.
currency	Order currency(USD,EUR,RUB and others).
receiver	Order cleavage instructions.

Example by scheme 3, you can find in '/examples/Order/settlement_scheme_3.php'

Full documentation you can request support@fondy.eu

Host-to-host API supports the following text formats:

• json

P2P card credit

Example:

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

   \Cloudipsp\Configuration::setMerchantId(1000);
   \Cloudipsp\Configuration::setCreditKey('test');
   $TestOrderData = [
      'currency' => 'USD',
      'amount' => 1000,
      'receiver_card_number' => '4444555511116666'
   ];
   //Call method to generate order
   $orderData = \Cloudipsp\P2pcredit::start($TestOrderData);

(array) getData() — returns payment data.

Required request Parameters:

Parameters	Description
order_id	Order ID which is generated by merchant.
merchant_id	Merchant unique ID.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
currency	Order currency(USD, EUR, RUB and others).
amount	Order amount in cents without separator.
receiver_card_number	Card number.
receiver_rectoken	Card token — token to credit card without transferring full card number.

Host-to-host API supports the following text formats:

• form
• xml
• json

Payments

Payment reports

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  $Data = [
        "date_from" => date('d.m.Y H:i:s', time() - 3600),
        "date_to" => date('d.m.Y H:i:s'),
  ];
  $reports = \Cloudipsp\Payment::reports($Data);
  var_dump($reports->getData());

(array) getData() — returns payment report data.

Required request Parameters:

Parameters	Description
merchant_id	Merchant unique ID.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
date_from	Start order datetime.
date_to	End order datetime.

Host-to-host API supports the following text formats:

• xml
• json

Payment using card token

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  $recurringData = [
        'currency' => 'USD',
        'amount' => 1000,
        'rectoken' => 'token'
  ];
  $recurring_order = Cloudipsp\Payment::recurring($recurringData);
  var_dump($recurring_order->getData());

(array) getData() — returns payment info.

(bool) isApproved() — method to check if recurring is successful.

Required request Parameters:

Parameters	Description
order_id	Order ID. Can be generated by SDK.
merchant_id	Merchant unique ID.
order_desc	Order description. Generated by merchant in UTF-8. Can be generated by SDK.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
amount	Order amount in cents without separator.
currency	Order currency(USD, EUR, RUB and others).
rectoken	Card token — token to access card funds without cardholder interaction.

Host-to-host API supports the following text formats:

• xml
• json
• form

Subscription

Subscription url

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  \Cloudipsp\Configuration::setApiVersion('2.0');
  $data = [
        'currency' => 'USD',
        'amount' => 1000, // convert to 10.00$
        'recurring_data' => [
            'start_time' => '2021-12-24',
            'amount' => 1000,
            'every' => 30,
            'period' => 'day',
            'state' => 'y',
            'readonly' => 'y'
        ]
    ];
  $url = \Cloudipsp\Subscription::url($data);
  $data = $url->getData();

(array) getData() — returns checkout url.

(null) toCheckout() — redirect to checkout page.

Required request Parameters:

Parameters	Description
order_id	Order ID. Can be generated by SDK.
merchant_id	Merchant unique ID.
order_desc	Order description. Generated by merchant in UTF-8. Can be generated by SDK.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
amount	Order amount in cents without separator.
currency	Order currency(USD,EUR,RUB and others).
recurring_data	Subscription info.
start_time	Start calendar payment format("Y-m-d").
amount	Subscription amount.
every	Frequency of payments(number).
period	Frequency of payments('day','month','week').
state	Checkout calendar state "y" - enabled.
readonly	Checkout calendar readonly.

Host-to-host API v2.0 supports the following text formats:

• json

All other params look in provider documentation.

Subscription token

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  \Cloudipsp\Configuration::setApiVersion('2.0');
  $data = [
          'order_desc' => 'tests SDK',
          'currency' => 'USD',
          'amount' => 1000,
          'merchant_data' => [
              'custom_data1' => 'Some string'
          ],
           'recurring_data' => [
                      'start_time' => '2021-12-24',
                      'amount' => 1000,
                      'every' => 30,
                      'period' => 'day',
                      'state' => 'y',
                      'readonly' => 'y'
           ]
    ];
  $token = \Cloudipsp\Subscription::token($data);

(array) Returns checkout token.

Required request Parameters:

Subscription stop

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  \Cloudipsp\Configuration::setApiVersion('2.0');
  $cancel = Cloudipsp\Subscription::stop($order_id);

(array) Returns info about calendar status.

PCIDSS Accept purchase

Step One

Example 3ds card:

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

   \Cloudipsp\Configuration::setMerchantId(1396424);
   \Cloudipsp\Configuration::setSecretKey('test');
   $TestOrderData = [
           'order_id' => time(),
           'card_number' => '4444555566661111', //testing card with 3ds
           'cvv2' => '333',
           'expiry_date' => '1232',
           'currency' => 'USD',
           'amount' => 1000,
           'client_ip' => '127.2.2.1'
   ];
   //Call method to generate order
   $orderData = Cloudipsp\Pcidss::start($TestOrderData);
   if($orderData->is3ds())
      $form = \Cloudipsp\Pcidss::get3dsFrom($orderData->getData(), $response_url . 'response_url');

(array) getData() — returns payment data.

(bool) is3ds() — check if is 3ds response.

(string) get3dsFrom($responseData, 'response_url') — generating form for step two if 3ds response.

Required request Parameters:

Parameters	Description
order_id	Order ID which is generated by merchant.
merchant_id	Merchant unique ID.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
currency	Order currency(USD, EUR, RUB and others).
amount	Order amount in cents without separator.
card_number	Card number.
cvv2	CVV card code.
expiry_date	Expaire date of card format 'MMYY'.
client_ip	Client IP.

Host-to-host API supports the following text formats:

• form
• xml
• json

Step Two

Example 3ds card:

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

   \Cloudipsp\Configuration::setMerchantId(1396424);
   \Cloudipsp\Configuration::setSecretKey('test');
   if (!empty($_POST)) {
       $dataTo3dsSubmit = $_POST;
       $dataTo3dsSubmit['order_id'] = 'order_id_from_prev_step'; // adding order id from prev step
       $orderData = \Cloudipsp\Pcidss::submit($dataTo3dsSubmit);
   }

Submitting result generated form from step one

(array) getData() — returns payment data.

Host-to-host API supports the following text formats

• form
• xml
• json

Card verification

Payment card verification url

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  $data = [
        'verification_type' => 'code', //default - amount
        'currency' => 'USD',
        'amount' => 100
  ];
  $url = \Cloudipsp\Verification::url($data);
  $data = $url->getData();

The request must contain additional parameter verification and verification_type

(array) getData() — returns verification url data.

(null) toCheckout() — redirect to verification checkout page.

Required request Parameters:

Parameters	Description
order_id	Order ID. Can be generated by SDK.
merchant_id	Merchant unique ID.
order_desc	Order description. Generated by merchant in UTF-8. Can be generated by SDK.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
verification	If Y order will be automatically reversed by provider after successful approval.
verification_type	'code' or 'amount'. Default is amount.
currency	Order currency(USD, EUR, RUB and others).
amount	Order amount in cents without separator.

Host-to-host API supports the following text formats:

• form
• xml
• json

All other params look in provider documentation.

Payment verification form

Example:

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

  \Cloudipsp\Configuration::setMerchantId(1396424);
  \Cloudipsp\Configuration::setSecretKey('test');
  $data = [
          'verification_type' => 'code', //default - amount
          'currency' => 'USD',
          'amount' => 100
  ];
  $form = \Cloudipsp\Verification::form($data);

(string) returns payment form as string.

Required request Parameters:

Parameters	Description
order_id	Order ID. Can be generated by SDK.
merchant_id	Merchant unique ID.
order_desc	Order description. Generated by merchant in UTF-8. Can be generated by SDK.
signature	Order signature. Required to verify merchant request consistency and authenticity. Can be generated by SDK.
amount	Order amount in cents without separator.
currency	Order currency(USD,EUR,RUB and others).
verification	If Y order will be automatically reversed by FONDY after successful approval.
verification_type	'code' or 'amount'. Default is amount.

All other params look in provider documentation.

Result

Server callback url

Example handling result

<?php
/**
 * Setting up testing configuration
 * All testing details you can find here https://docs.fondy.eu/docs/page/2/
 */
require_once 'configuration.php';
require_once SDK_ROOTPATH . '/../vendor/autoload.php';
/**
 * Getting payment result (server_callback_url)
 * Signature validation example server_callback_url
 * you can get params by yourself, or sdk can got it
 */
try {
    $result = new \Cloudipsp\Result\Result();
    /**
      * or you can build with data parsed by yourself 
      * $result = new \Cloudipsp\Result\Result($_POST, $secretKey, $requestType, true);
    */
    if ($result->getData())
        var_dump($result->getData());
    else
        die('No data');
    } catch (\Exception $e) {
        echo "Fail: " . $e->getMessage();
    }

(array) getData() — returns callback data.

(bool) isValid() — returns if callback valid (checking signature).

(bool) isApprove() — returns payment successfully include (checking signature).

Result is always returned in request context in the same content-type. So if request is sent in JSON, response will be sent in JSON format too. Response for such request will be interim and will contain URL where customer must be redirected to payment page.

Sending request in interaction scheme A does not assume getting response in request context. Final response will be returned to merchant URL, specified in response_url and server_callback_url Parameters.

Errors

The basic exception list:

Parameters	Description
Merchant ID is empty or invalid.	Set the merchant id or check if it numeric.
Secret Key is empty or invalid.	Set the secret key or check if it string.
Required param "param_name" is empty	Some api required parameter is empty. Watch docs.
Required param "param_name" is missing	Some api required parameter is missing. Watch docs.
Invalid signature signature....response_signature_string......	Check data, some parameters not accepted by provider api.
Request is incorrect. Request ID: 3wq8EvammIxih	Invalid data or method not allowed for merchant.