API FONDYVersion 1.0

Step by step instruction to accept payments with Fondy JavaScript SDK

First payment

1. Install Fondy JavaScript SDK in your project

Node

If you’re using Npm in your project, you can add ipsp-js-sdk dependency to package.json with following command:

npm i --save ipsp-js-sdk

or add dependency manually:

{
  "dependency": {
    "ipsp-js-sdk":"^1.0"
  }
}

Bower

If you’re using Bower in your project, you can run the following command:

bower install ipsp-js-sdk

Manually

If you do not use NodeJS, you can download the latest release. Or clone from GitHub the latest developer version

git clone git@github.com:cloudipsp/ipsp-js-sdk.git

Quick start

<script src="https://unpkg.com/ipsp-js-sdk@latest/dist/checkout.min.js"></script>

Detailed instalation instruction: https://github.com/cloudipsp/ipsp-js-sdk.

2. Develop html credit card form using your own design.

Basic template

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  </head>
  <body>
    <script src="https://unpkg.com/ipsp-js-sdk@latest/dist/checkout.min.js"></script>
    <script>
    $checkout('Api').scope(function(){
        this.request('api.checkout.form','request', { Parameters } ).done(function(model){
            model.sendResponse();
            console.log(model.attr('order'));
        }).fail(function(model){
            console.log(model.attr('error'));
        });
    });
    </script>
  </body>
</html>

Basic template example: https://github.com/cloudipsp/ipsp-js-sdk#basic-template

3. Create order using Integration Schema C for JavaScript SDK.

Add parameters required_rectoken=Y and server_callback_url in your request to obtain recurring token in server callback (rectoken parameter).

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": "TestOrder_SDK1",
    "currency": "USD",
    "merchant_id": 1396424,
    "order_desc": "Test payment",
    "amount": 1000,
    "required_rectoken": "Y",
    "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"
  }
}

Documentation: https://docs.fondy.eu/docs/page/3/?la=en#chapter-3-6-c.
Save host-to-host  token parameter from response.

4. Load host-to-host token from step 3 in your card details form.

Submit parameters

Parameters:

{
 "payment_system":"card",
 "token":"host-to-host generated token",
 "card_number":"16/19-digits number",
 "expiry_date":"Supported formats: MM/YY, MM/YYYY, MMYY, MMYYYY",
 "cvv2":"3-digits number"
 }

from card form to payment gateway using JavaScript API $checkout('Api').
Instruction: https://github.com/cloudipsp/ipsp-js-sdk#host-to-host-token

5. Use .on('success') and .on('error') JavaScript callbacks to get result on payment processing.

success – order is approved and amount will be charged
error – order is declined and amount will not be charged

model.attr('error.message') will contain localized error message in case of payment decline. Order information on order status and details will be returned in model.data.order.order_data

JavaScript callback example:

console.log('success',JSON.stringify(model.attr("order").order_data));
{
  "rrn": "",
  "masked_card": "444455XXXXXX1111",
  "sender_cell_phone": "",
  "response_signature_string": "**********|10000|USD|10000|123456|444455|VISA|USD|06|444455XXXXXX1111|[]|1396424|Order_1396424_ZtP6E6IQMC_1520944420|approved|13.03.2018 14:33:40|85233820|card|success|0|client@example.com|0|purchase",
  "response_status": "success",
  "sender_account": "",
  "fee": "",
  "rectoken_lifetime": "",
  "reversal_amount": "0",
  "settlement_amount": "0",
  "actual_amount": "10000",
  "order_status": "approved",
  "response_description": "",
  "verification_status": "",
  "order_time": "13.03.2018 14:33:40",
  "actual_currency": "USD",
  "order_id": "Order_1396424_ZtP6E6IQMC_1520944420",
  "parent_order_id": "",
  "merchant_data": "[]",
  "tran_type": "purchase",
  "eci": "06",
  "settlement_date": "",
  "payment_system": "card",
  "rectoken": "",
  "approval_code": "123456",
  "merchant_id": 1396424,
  "settlement_currency": "",
  "payment_id": 85233820,
  "product_id": "",
  "currency": "USD",
  "card_bin": 444455,
  "response_code": "",
  "card_type": "VISA",
  "amount": "10000",
  "sender_email": "client@example.com",
  "signature": "b39ac49a1bdf4bbd7fc09e990fbba63197be67d0"
}

Example: https://jsfiddle.net/fondyeu/jdc9o5cx/

6. Process final response received as server callbacks to server_callback_url.

Format of final response: https://docs.fondy.eu/docs/page/3/?la=en#chapter-3-2

Response example:

success {
  "rrn": "",
  "masked_card": "444455XXXXXX1111",
  "sender_cell_phone": "",
  "response_signature_string": "**********|10000|USD|10000|123456|444455|VISA|USD|06|444455XXXXXX1111|[]|1396424|Order_1396424_ZtP6E6IQMC_1520944420|approved|13.03.2018 14:33:40|85233820|card|success|0|client@example.com|0|purchase",
  "response_status": "success",
  "sender_account": "",
  "fee": "",
  "rectoken_lifetime": "",
  "reversal_amount": "0",
  "settlement_amount": "0",
  "actual_amount": "10000",
  "order_status": "approved",
  "response_description": "",
  "verification_status": "",
  "order_time": "13.03.2018 14:33:40",
  "actual_currency": "USD",
  "order_id": "Order_1396424_ZtP6E6IQMC_1520944420",
  "parent_order_id": "",
  "merchant_data": "[]",
  "tran_type": "purchase",
  "eci": "06",
  "settlement_date": "",
  "payment_system": "card",
  "rectoken": "",
  "approval_code": "123456",
  "merchant_id": 1396424,
  "settlement_currency": "",
  "payment_id": 85233820,
  "product_id": "",
  "currency": "USD",
  "card_bin": 444455,
  "response_code": "",
  "card_type": "VISA",
  "amount": "10000",
  "sender_email": "client@example.com",
  "signature": "b39ac49a1bdf4bbd7fc09e990fbba63197be67d0"
}

Save recurring token from rectoken parameter and masked card number in format 4444 55XX XXXX 1111 from masked_card in callback

Recurring payment

Send rectoken to endpoint https://api.fondy.eu/api/recurring to make recurring charge.

Documentation: https://docs.fondy.eu/docs/page/10/

One-click payment

Perform step 1-3 from “First payment” instruction. Optimize card form design to show masked card and request cvv2 from client
Load host-to-host token from step 3 and rectoken from final response in your card details from.
In case of one-click payment rectoken will be used insted of card_number and expiry_date

Submit parameters

 {
 "payment_system":"card",
 "token":"host-to-host generated token",
 "rectoken":"rectoken from final response",
 "cvv2":"3-digits number"
 }

Process with step 5-6 for one-click payment to receive payment result in callback

Additional documentation:

Connect to FONDY and learn more!