API FONDYVersion 1.0

Request parameters

ParameterTypeDescriptionSample
order_idstring(1024)Order ID which is generated by merchant.

mandatory
ID1234
merchant_idinteger(12)Merchant unique ID. Generated by FONDY during merchant registration.

mandatory
1
order_descstring(1024)Order description. Generated by merchant in UTF-8 always

mandatory
Hotel booking №1234 Antalya Resort
signaturestring(40)Order signature. Required to verify merchant request consistency and authenticity. Signature generation algorithm please see at Signature generation for request and response

mandatory
1773cf135bd89656131134b98637894dad42f808
amountinteger(12)Order amount in cents without separator

mandatory
1020 (EUR)
means 10 euros and 20 cents
currencystring(3)

Order currency. Supported values:
EUR — Euro
USD — US Dollar
GBP — Pound sterling mandatory
CZK — Czech Republic Koruna
UAH — Ukrainian Hryvnia

Full list of supported currencies.

EUR
versionstring(10)Protocol version.

Default value: 1.0.1
Version 1.0 is deprecated
If 1.0.1 passed, additional_info parameter will be returned in the callback
response_urlstring(2048)Merchant site URL, where a customer will be redirected after payment completion
http://site.com/responseurl
server_callback_urlstring(2048)Merchant site URL, where host-to-host callback will be sent after payment completion. See Receiving Callbacks for more details on callbacks.
http://site.com/callbackurl
payment_systemsstring(1024)Payment systems which can be used for payment by the customer at FONDY payment page. Systems must be separated by a comma or semicolon.
Supported values: see. Supported payment systems

Default value: is set from merchant settings in FONDY merchant portal
card, banklinks_eu, banklinks_pl
default_payment_systemstring(25)Payment system which will be shown to the customer at FONDY payment page first.
Supported values: see. Supported payment systems
card
lifetimeinteger(9)Order lifetime in seconds. After this time, the order will be given the status of ‘expired’ if the client has not paid it

Default value: 36000
Maximum allowed value: 69120000
600
merchant_datastring(2048)Any arbitrary set of data that a merchant wants to get back in the response to response_url or/and server_callback_url, and also in reports 
preauthstring(1)Parameter supported only for Visa/MasterCard payment method
N — the amount is debited from the customer’s card immediately and settled to the merchant account, in accordance with the rules of settlements.
Y — amount held on the customer card and not charged until the merchant sends a ‘capture’ request to confirm

Default value: N
N
sender_emailstring(254)Customer email 
descriptorstring(21)Dynamic descriptor 
delayedstring(1)Delayed order flag.
Y — allows the customer to pay the order during period sent by the merchant in lifetime parameter. Merchant must expect several host-to-host callbacks and browser redirects at the same order. Customer will have the possibility to try to pay the same order_id, if the previous attempt failed
N — after payment is declined order_id customer will be redirected to the merchant site to recreate the order. In this case, only one callback will be sent to server_callback_url

Default value: Y
 
langstring(2)Payment page language. Supported values:
ru – Russian
uk – Ukrainian
en – English
lv – Latvian
fr – French
cs – Czech
ro – Romanian
it – Italian
sk – Slovak
pl – Polish
es – Spanish
hu – Hungarian
de – German
 
product_idstring(1024)Merchant product or service id 
required_rectokenstring(1)Flag which indicates whether FONDY must return card token — token to access card funds without cardholder interaction

Default value: N
Y
verificationstring(1)If Y order will be automatically reversed by FONDY after successful approval

Default value: N
Y
verification_typestring(25)amount – amount submitted from merchant will be held on card
code – amount submitted from merchant will be held on card. Also, cardholder have to enter 4-characters code to pass verification

Default value: amount
Y
rectokenstring(40)Card token — token to access card funds without cardholder interaction
544d3f86237886b6404d8b000f6a7d71c45410b7
receiver_rectokenstring(40)Card token — token to credit card without transferring full card number
544d3f86237886b6404d8b000f6a7d71c45410b7
design_idinteger(6)ID of design which is set in merchant portal
123
subscriptionstring(1)Y – enable scheduled payments
N – by default, disable scheduled payments
Y/N
subscription_callback_urlstring(2048)Merchant site URL, where host-to-host callback will be sent after scheduled payment completion 

Parameters of the final response

ParameterTypeDescriptionResponse sample
order_idstring(1024)Order ID which is generated by merchant.
merchant_idinteger(12)Merchant unique ID. Generated by FONDY during merchant registration.1
amountinteger(12)Order amount in cents without separator1020 (EUR)
means 10 euros and 20 cents
currencystring(3)Order currency. Supported values:
EUR — Euro
USD — US Dollar
GBP — Pound sterling mandatory
CZK — Czech Republic Koruna
UAH — Ukrainian Hryvnia</p/>
order_statusstring(50)Order processing status. Can contain the following values:
created — order has been created, but the customer has not entered payment details yet; merchant must continue to request the status of the order
processing — order is still in processing by payment gateway; merchant must continue to request the status of the order
declined — order is declined by FONDY payment gateway or by a bank or by an external payment system
approved — order completed successfully, funds are held on the payer’s account and soon will be credited of the merchant; merchant can provide the service or ship goods
expired — order lifetime expired.
reversed — previously approved transaction was fully reversed. In this case, parameter reversal_amount will be equal to actual_amount
response_statusstring(50)Request processing status. If parameters sent by merchant did not pass validation then failure, else success
signaturestring(40)Order signature. Required to verify merchant request consistency and authenticity. Signature generation algorithm please see at Signature generation for request and response
1773cf135bd89656131134b98637894dad42f808
tran_typestring(50)Supported values:
purchase
verification
p2p credit
p2p transfer
settlement — split payments
reverse
sender_cell_phonestring(16)Customer mobile phone number
sender_accountstring(50)Customer payment account
masked_cardstring(19)Masked card number444444XXXXXX5555
card_bininteger(6)Card bin — usually first 6 digits444444
card_typestring(50)Supported values:
VISA, MasterCard
rrnstring(50)Commonly not unique transaction ID returned by bank.
approval_codestring(6)Commonly not unique authorization code returned by bank.
response_codeinteger(4)Order decline response code. Possible codes see in Response codes
response_descriptionstring(1024)Order response code description, see Response codes
reversal_amountinteger(12)The total amount of all reversals for current order
settlement_amountinteger(12)The settlement amount for current order
settlement_currencystring(3)The currency of order settlement
order_timestring(19)Order creation date DD.MM.YYYY hh:mm:ss21.12.2014 11:21:30
settlement_datestring(10)Settlement date in format DD.MM.YYYY21.12.2014
eciinteger(2)Ecommerce Indicator – parameter specifies whether 3DSecure authentication was performed or not. Supported values:
5 — full 3DSecure authentication performed
6 — merchant supports 3DSecure, but issuing bank does not
7 — neither merchant nor issuing bank supports 3DSecure
feeinteger(12)Fee charged by FONDY
payment_systemstring(50)Payment system which was used for payment. Supported payment systems list see Supported payment systemscard
sender_emailstring(254)Customer email
payment_idinteger(19)Unique payment ID generated by FONDY payment gateway
actual_amountinteger(12)The actual amount held or charged from card.
actual_currencystring(3)The actual currency authorized from card
product_idstring(1024)Merchant product or service ID
merchant_datastring(2048)Any arbitrary set of data that a merchant sends in a request
verification_statusstring(50)Code verification result
Supported values:
verified — card successfully verified with code
incorrect — incorrect code entered but limit not exceeded yet
failed — allowed number of invalid attempts to enter code exceeded
created — verification code created but not entered yet
rectokenstring(40)Flag which indicates whether FONDY must return card token — token to access card funds without cardholder interaction
da39a3ee5e6b4b0d3255bfef95601890afd80709
rectoken_lifetimestring(19)Token lifetime in format DD.MM.YYYY hh:mm:ss
01.01.2018 00:00:00
additional_infostring(20480)Additional field in JSON format
{
"bank_name": "Some bank in US country",
"bank_country": "US",
"bank_response_code": "decln_1000",
"card_product": "DEBIT",
"card_category": "CLASSIC",
"settlement_fee": 0.2,
"capture_status": "captured",
"client_fee": 0.3,
"ipaddress_v4": "8.8.8.8",
"capture_amount": 200,
"card_type": "VISA",
"reservation_data": null,
"bank_response_description": "General decline",
"transaction_id": 1058755083,
"timeend":"10.01.2018 11:21:30"
"card_number": "4444555566661111"
}

Parameters of interim response

ParameterTypeDescriptionSample
response_statusstring(50)if no error occurred then always return successsuccess
checkout_urlstring(20)48FONDY payment page URL where merchant site must redirect customer to enter payment details
https://pay.fondy.eu/checkout?token=e0a5d4f331806d1e2feb80353b4c44bf6751fc8c
payment_idinteger(19)Unique payment ID generated by FONDY payment gateway 

Parameters of response in case of error

ParameterTypeDescriptionSample
response_statusstring(50)always returns failurefailure
error_codeinteger(4)Response decline code. Supported values see Response codes 
error_messagestring(1024)Response code description. See Response codes 

Signature generation for request and response (parameter signature)

Signature is generated by SHA1 function which is applied to the string which contains merchant password and all parameters concatenated in alphabetic order and separated by | symbol

Example:

Merchant request:

{
  "request":{
    "order_id":"test123456",
    "order_desc":"test order",
    "currency":"USD",
    "amount":"125",
    "signature":"df38818facfbfd79953fa847667dac73a1291127",
    "merchant_id":"1396424"
  }
}

string used for signature build:

test|125|USD|1396424|test order|test123456

If parameter is absent or is empty then there is no need to add | symbol.

Signature validation example of response_url and server_callback_url POST response using PHP SDK:

function getSignature( $merchant_id , $password , $params = array() ){
 $params['merchant_id'] = $merchant_id;
 $params = array_filter($params,'strlen');
 ksort($params);
 $params = array_values($params);
 array_unshift( $params , $password );
 $params = join('|',$params);
 return(sha1($params));
}

Example file Signature.php

 
namespace Ipsp;
/**
 * Class Signature
 * @package Ipsp
 */
class Signature {
    /**
     * @var
     */
    private static $password;
    /**
     * @var
     */
    private static $merchant;
    /**
     * Set merchant password
     * @param String $password
     * @return mixed
     */
    public static function password($password){
        self::$password = $password;
    }
    /**
     * Set merchant id
     * @param String $merchant
     * @return mixed
     */
    public static function merchant( $merchant ){
        self::$merchant = $merchant;
    }
    /**
     * Generate request params signature
     * @param array $params
     * @return string
     */
    public static function generate(Array $params){
        $params['merchant_id'] = self::$merchant;
        $params = array_filter($params,'strlen');
        ksort($params);
        $params = array_values($params);
        array_unshift( $params , self::$password );
        $params = join('|',$params);
        return(sha1($params));
    }
    /**
     * Sign params with signature
     * @param array $params
     * @return array
     */
    public static function sign(Array $params){
        if(array_key_exists('signature',$params)) return $params;
        $params['signature'] = self::generate($params);
        return $params;
    }
    /**
     * Clean array params
     * @param array $data
     * @return array
     */
    public static function clean(Array $data){
        if( array_key_exists('response_signature_string',$data) )
            unset( $data['response_signature_string'] );
        unset( $data['signature'] );
        return $data;
    }
    /**
     * Check response params signature
     * @param array $response
     * @return bool
     */
    public static function check(Array $response){
        if(!array_key_exists('signature',$response)) return FALSE;
        $signature = $response['signature'];
        $response  = self::clean($response);
        return $signature == self::generate($response);
    }
}

Signature verification with class Signature

require_once 'Signature.php';
# import Signature class from namespace
use Ipsp\Signature;
# setup merchant id and password
Signature::merchant(1396424);
Signature::password('test');
if(Signature::check($response)){
    echo 'signature is valid. Now we can complete purchase';
} else{
    echo 'bad signature throw error'
}

Solving problems with signature parameter generation and validation

There are two typical situations when the signature parameter verification error occurs.

  1. If the request for the purchase/recurring payment, reverse/status or any other request with the parameter signature is sent from merchant to the FONDY API, and the response is returned: Invalid signature.
  2. If the FONDY server returned a POST response or callback to server_callback_url or response_url, but when you try to generate a signature and compare it with the signature parameter from the POST response, the signatures do not match

Consider both cases:

  1. If the request is sent to the FONDY API, and the response is returned as “Invalid signature signature: `6bd069be8a6e2f2bbe176df00ba63cc681ca38aa`; response_signature_string: `**********|125|USD|1396424|demo order 789|Demo123456`”, perform the following checks:
    • check that you used the correct payment key from the Technical Settings in the Merchant Portal:


    • if the request contains non-Latin encoding, then it is sent in encoding UTF-8
    • make sure that a parameter with a value of 0 is not null by your programming language
    • log the line in the program code to which you apply SHA1 during the generation of the signature parameter. Compare it with the string that returned in the error text (marked in red): “Invalid signature signature: `6bd069be8a6e2f2bbe176df00ba63cc681ca38aa`; response_signature_string: `**********|125|USD|1396424|demo order 789|Demo123456`“. Note that in the text of the error the merchant’s payment key will be masked by *
    • check if you send empty parameters in the API request. If yes, then in the line that participates in the signature, the | separator symbol for each such empty parameter does not need to be included
    • if you are developing in the PHP programming language, use the example function getSignature:
      function getSignature( $merchant_id , $password , $params = array() ){
       $params['merchant_id'] = $merchant_id;
       $params = array_filter($params,'strlen');
       ksort($params);
       $params = array_values($params);
       array_unshift( $params , $password );
       $params = join('|',$params);
       return(sha1($params));
      }
      
    • make sure that the result of the SHA1 function is lowercase. Correct: 6bd069be8a6e2f2bbe176df00ba63cc681ca38aa. Incorrect: 6BD069BE8A6E2F2BBE176DF00BA63CC681CA38AA
    • make sure that the signature parameter is not included in your signature calculation
    • make sure that if you use the API endpoint /api/recurring, then you only include the necessary parameters in the signature, but not those from the /api/redirect endpoint
  2. If the server FONDY returned a POST response to the pages specified in the server_callback_url or response_url parameters, but when you try to generate a signature and compare it with the signature parameter in the POST response, the signature does not match

Response example from FONDY (JSON):

{
 "rrn": "429417347068",
 "masked_card": "444455XXXXXX6666",
 "sender_cell_phone": "",
 "response_signature_string": "**********|3324000|EUR|3324000|027440|444455|VISA|EUR|444455XXXXXX6666|1396424|
  14#1500639628|approved|21.07.2017 15:20:27|51247263|card|success|0|429417347068|test@FONDY.eu|0|purchase",
 "response_status": "success",
 "sender_account": "",
 "fee": "",
 "rectoken_lifetime": "",
 "reversal_amount": "0",
 "settlement_amount": "0",
 "actual_amount": "3324000",
 "order_status": "approved",
 "response_description": "",
 "verification_status": "",
 "order_time": "21.07.2017 15:20:27",
 "actual_currency": "EUR",
 "order_id": "14#1500639628",
 "parent_order_id": "",
 "merchant_data": "",
 "tran_type": "purchase",
 "eci": "",
 "settlement_date": "",
 "payment_system": "card",
 "rectoken": "",
 "approval_code": "027440",
 "merchant_id": 1396424,
 "settlement_currency": "",
 "payment_id": 51247263,
 "product_id": "",
 "currency": "EUR",
 "card_bin": 444455,
 "response_code": "",
 "card_type": "VISA",
 "amount": "3324000",
 "sender_email": "test@FONDY.eu",
 "signature": "47bdcaf61b99edd31e3ec7913225a14d2ce07575"
}

To diagnose the cause of a signature mismatch, follow these steps:

  • make sure that the parameter with a value of 0 is not brought to empty or null in your programming language
  • make sure that the response_signature_string and signature parameters are not included in the signature calculation (the response_signature_string parameter is returned only if the merchant is in test mode and contains hint how the signature was formed in response)
  • if the request contains non-Latin letters, then it is sent in UTF-8
  • in the program code, pledge a line to which you apply SHA1 during the formation of the signature parameter. Compare it with the string that returned in the response_signature_string
  • parameter

  • Check if empty parameters are returned in the response. If yes, then in the string which participates in the signature, it is not necessary to include the symbol separator | for each empty parameter
  • If you are developing in the PHP programming language, use the getSignature function:
    function getSignature( $merchant_id , $password , $params = array() ){
     $params['merchant_id'] = $merchant_id;
     $params = array_filter($params,'strlen');
     ksort($params);
     $params = array_values($params);
     array_unshift( $params , $password );
     $params = join('|',$params);
     return(sha1($params));
    }
    
  • make sure that the result of the SHA1 function is lowercase. Correct: 6bd069be8a6e2f2bbe176df00ba63cc681ca38aa. Incorrect: 6BD069BE8A6E2F2BBE176DF00BA63CC681CA38AA

Request generation

Request to FONDY payment gateway can be sent in several methods

  1. Interaction scheme A (most common)
    Merchant builds order HTML form on its website and POSTs it from merchant page to payment gateway hosted page using browser redirection
    Endpoint: https://pay.fondy.eu/api/checkout/redirect/
    It is the most simple way to integrate your site. So if you do not know which scheme to use – then use scheme A

    Example for interaction scheme A

    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8">
      </head>
      <body>
        <form name="tocheckout" method="POST" action="https://pay.fondy.eu/api/checkout/redirect/">
          <input type="text" name="server_callback_url" value="https://site.com/callback/">
          <input type="text" name="response_url" value="https://site.com/responsepage/">
          <input type="text" name="order_id" value="test4207135583">
          <input type="text" name="order_desc" value="Test payment">
          <input type="text" name="currency" value="USD">
          <input type="text" name="amount" value="100">
          <input type="text" name="signature" value="1773cf135bd89656131134b98637894dad42f808">
          <input type="text" name="merchant_id" value="1">
          <input type="submit">
        </form>
      </body>
    </html>
    
  2. Interaction scheme B
    Merchant builds POST parameters on the server side and directly POSTs it from merchant server to payment gateway server, for example with curl
    Endpoint: https://pay.fondy.eu/api/checkout/url/

    Interaction scheme B API supports following text transfer protocols: URL encoded, XML, JSON. Best cases to use this method are:

    • generating a request from the merchant server to make POST parameters more secured and prevent them from disclosure
    • generating an invoice for a customer by sending payment page url via email, social networks, SMS

    Example host-to-host for interaction scheme B (JSON)

    Request

    curl -i -X POST \
     -H "Content-Type:application/json" \
     -d \
    '{
     "request": {
     "server_callback_url": "http://myshop/callback/",
     "order_id": "TestOrder2",
     "currency": "USD",
     "merchant_id": 1396424,
     "order_desc": "Test payment",
     "amount": 1000,
     "signature": "91ea7da493a8367410fe3d7f877fb5e0ed666490"
     }
    }' \
     'https://pay.fondy.eu/api/checkout/url'

    Normal response

    {
      "response":{
        "response_status":"success",
        "checkout_url":"https://pay.fondy.eu/checkout?token=afcb21aef707b1fea2565b66bac7dc41d7833390"
      }
    }
    

    Response in case of error

    {
      "response":{
      "response_status":"failure",
      "error_message":"Parameter `amount` is mandatory",
      "error_code":"1008"
      }
    }
    

    Example host-to-host interim response B (XML)

    Request

    curl -i -X POST \
     -H "Content-Type:application/xml" \
     -d \
    '
    <?xml version="1.0" encoding="UTF-8"?>
    <request>
     <response_url>http://myshop/callback/</response_url>
     <order_id>TestOrderXML211</order_id>
     <order_desc>Test payment</order_desc>
     <currency>USD</currency>
     <amount>100</amount>
     <signature>f0174cbeb6f3a400550481aa2fca0879626c902d</signature>
     <merchant_id>1396424</merchant_id>
    </request>
    ' \
     'https://pay.fondy.eu/api/checkout/url'

    Normal response

    <?xml version="1.0" encoding="UTF-8"?>
    <response>
      <response_status>success</response_status>
      <checkout_url>https://pay.fondy.eu/checkout?token=6c67efad5fd68921f58836cabc2a3d27c5f02b23</checkout_url>
    </response>
    

    Response in case of error

    <?xml version="1.0" encoding="UTF-8"?>
    <response>
      <response_status>failure</response_status>
      <error_message>Parameter `amount` is mandatory</error_message>
      <error_code>1008</error_code>
    </response>
    

    Example host-to-host for interaction scheme B (URL encoded form)

    Request

    curl -i -X POST \
     -H "Content-Type:application/x-www-form-urlencoded" \
     -d 'response_url=http://myshop/callback/&order_id=TestOrderURLEncode211&order_desc=Test payment&currency=USD&amount=100&signature=b7acb85c7f02882049c9e19813025f27cb09ad63&merchant_id=1396424' \
    'https://pay.fondy.eu/api/checkout/url'

    Normal response

    response_status=success&checkout_url=http%3A%2F%2Flocalhost%2Fcheckout%3Ftoken%3D643f3cea682e066f142099a76b0fa9d1613969dc

    Response in case of error

    response_status=failure&error_message=Parameter%20%60amount%60%20is%20mandatory&error_code=1008
  3. Interaction scheme C
    This scheme is used mostly for JavaScript SDK  
    This scheme is similar to scheme B. The difference is in response: instead of checkout_url, parameters token will be returned.
    Endpoint: https://pay.fondy.eu/api/checkout/token/

    Request

    curl -i -X POST \
     -H "Content-Type:application/json" \
     -d \
    '{
     "request": {
     "server_callback_url": "http://myshop/callback/",
     "order_id": "TestOrder2",
     "currency": "USD",
     "merchant_id": 1396424,
     "order_desc": "Test payment",
     "amount": 1000,
     "signature": "91ea7da493a8367410fe3d7f877fb5e0ed666490"
     }
    }' \
     'https://pay.fondy.eu/api/checkout/token'

    Normal response:

    {
      "response":{
        "response_status":"success",
        "token":"afcb21aef707b1fea2565b66bac7dc41d7833390"
      }
    }

    Response in case of error

    {
      "response":{
      "response_status":"failure",
      "error_message":"Parameter `amount` is mandatory",
      "error_code":"1008"
      }
    }

    This token is used in JavaScript SDK which allows to embed credit card form in your site and make a customized checkout page.

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. 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. The final response will be returned to merchant URL, specified in response_url and server_callback_url parameters.

Connect to FONDY and learn more!