API Reference

Flitt API provides powerful tools for implementation of online payments scenarios. You can develope your own payment flow of any type of complexity in a simple way with Flitt API: card payments, 3DSecure, subscriptions, splits, mobile wallets (Apple, GooglePay), online banking (Open Banking), local payment methods (iDEAL, Klarna, Blik, Sofort), electronic fiscalisation, etc.

API is organized around FORM-encoded request <-> response or JSON-encoded request <-> response bodies flow. So you can choose FORM or JSON for request body, and response body will have the same format as request.

You can use the Flitt API in test mode without any functionality restrictions. Depending on merchant test or live status you use, all requests are executed in corresponding test or live mode. Test mode never affects your live finances.

Authentication

All API requests must be made over HTTPS with method POST. Flitt uses parameter signature to authenticate each request. Signature is a result of SHA1 hash function, generated by merchant with its payment key.

Use payment key to build signature for each API request according to section Building signature. API request example:

curl -L 'https://pay.flitt.com/api/checkout/url' \
-H 'Content-Type: application/json' \
-d '{
    "request": {
        "server_callback_url": "...",
        "order_id": "test_order1231",
        "currency": "USD",
        "merchant_id": 1549901,
        "order_desc": "Test payment",
        "amount": 100,
        "signature": "487690517384b11725ac02d37f79fe677174291f"
    }
}'

Use test payment key, merchant id and cards from Testing mode section.

Note

When your merchant is in test mode, response can contain additional parameter response_signature_string which will be absent in the live mode. This is useful to analyze the reasons when request is rejected because an incorrect signature is build in request.

Warning

Do not send any sensitive information to Flitt API with test payment key and merchant taken from Testing mode section.

Declines and errors

Normal response means that the request is processed successfully. Normal response contains "response_status": "success"

Normal response

{
    "response": {
        "checkout_url": "https://pay.flitt.com/merchants/..../index.html?token=...",
        "payment_id": "738303484",
        "response_status": "success"
    }
}

Decline is a normal response, when request is processed successfully, but payment declined by some reason. Response with declined payment contains response_code and response_description parameters. Please refer Response codes section.

Normal response with decline

{
   "response": {
       "rrn": "",
       "masked_card": "444411XXXXXX6666",
       "sender_cell_phone": "",
       "sender_account": "",
       "currency": "USD",
       "fee": "",
       "reversal_amount": "0",
       "settlement_amount": "0",
       "actual_amount": "",
       "response_description": "General decline",
       "sender_email": "",
       "order_status": "declined",
       "response_status": "success",
       "order_time": "27.09.2022 22:43:38",
       "actual_currency": "",
       "order_id": "TestOrder238947272719",
       "tran_type": "purchase",
       "eci": "",
       "settlement_date": "",
       "payment_system": "card",
       "approval_code": "",
       "merchant_id": 1549901,
       "settlement_currency": "",
       "payment_id": 526886172,
       "card_bin": 444411,
       "response_code": 1000,
       "card_type": "VISA",
       "amount": "200",
       "signature": "fd5d3d61698ad80e91415eea42180db91b90fddd",
       "product_id": "",
       "merchant_data": "",
       "rectoken": "",
       "rectoken_lifetime": "",
       "verification_status": "",
       "parent_order_id": ""
   }
}

Error is returned in response when Flitt payment gateway can't process the request. In this case, response contains error_message and error_code parameters and "response_status": "failure".

Response with error

{
    "response": {
        "error_code": 1011,
        "error_message": "Parameter `amount` is missing",
        "request_id": "eZIT2An0VLAY2",
        "response_status": "failure"
    }
}