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 Antalia 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:
UAH — Ukrainian Hryvnia
RUB — Russian Rouble
USD — US Dollar
EUR — Euro
GBP — Pound sterling mandatory
CZK — Czech Republic Koruna

Full list of supported currencies.

EUR
versionstring(10)Protocol version.

Default value: 1.0
1.0
response_urlstring(2048)Merchant site URL, where customer will be redirected after payment completion

Default value: https://api.fondy.eu/checkout/responsepage
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 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
sepa,card,direct_debit
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(6)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
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 
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
 
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 transfering 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 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:
UAH — Ukrainian Hryvnia
RUB — Russian Rouble
USD — US Dollar
GBP — Pound sterling
CZK — Czech Republic Koruna
EUR — Euro
 
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 or partially reversed. In this case, parameter reversal_amount will be > 0
 
response_statusstring(50)Request processing status. If parameters sent by merchant did not pass validation then failure, else success 
signaturestring(40)Oredr 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)Total amount of all reversals for current order 
settlement_amountinteger(12)Settlement amount for current order 
settlement_currencystring(3)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 systemsQiwi
sender_emailstring(254)Customer email 
payment_idinteger(19)Unique payment ID generated by FONDY payment gateway 
actual_amountinteger(12)Actual amount after all reversals. 
actual_currencystring(3)Actual currency 
product_idstring(1024)Merchant product or service ID 
merchant_datastring(2048)Any arbitrary set of data that a merchant sends in 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

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://api.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:

<?php
require_once 'Signature.php';
use Ipsp\Signature;
Signature::merchant('ID мерчанта');
Signature::password('Ключ платежа');
if(Signature::check($_POST)){
    echo 'success';
} else{
    echo 'failure';
}

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://api.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://api.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="RUB">
          <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://api.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://api.fondy.eu/api/checkout/url'

    Normal response

    {
      "response":{
        "response_status":"success",
        "checkout_url":"https://api.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://api.fondy.eu/api/checkout/url'

    Normal response

    <?xml version="1.0" encoding="UTF-8"?>
    <response>
      <response_status>success</response_status>
      <checkout_url>https://api.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://api.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://api.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://api.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!