Skip to main content

API integration

Direct integration​

Direct integration will allow you to accept payments using your own payment page.

Interaction format:

An image from the static

info

To securely collect card data on the merchant side through direct integration, it is essential to have PCI DSS certification in place.

The direct integration with two-step payments involves the following features (in addition to those described for one-step payment):

  • In a request to the Financial Line API, the method parameter must contain the auth value.

The rest of the parameters are similar to those provided for one-step payments.

Request example:

$ curl "https://api.finline.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY {API_KEY}:{API_SECRET}" \
    -H "X-API-KEY: {ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "{POS_ID}",
      "mode":             "direct",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Depending on whether the request is full card data or a token, you need to pass the following parameters:

  • Using full card data: cc_number, exp_month, exp_year, card_cvv.
  • Using tokens: cc_token.

Response parameters:

ParameterTypeDescription
payment_idUUIDUnique Financial Line payment identifier
order_idString(≤256)Unique identifier of order
gateway_order_idGW_IDUnique order identifier in bank acquirer system.
billing_order_idBILLING_IDUnique Financial Line billing identifier
transaction_idUUIDFinancial Line transaction identifier
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEdirect
methodMETHODPayment method (auth or purchase)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionString(≤2048)Payment description
statusSTATUSTransaction status
status_codeSTATUS_CODEFinancial Line payment status code
status_descriptionSTATUS_DESCRIPTIONFinancial Line payment status code description
user_action_requiredBooleanEither customer action is required to proceed with payment
user_action_urlURLIf user_action_required is true then user should be redirected to this URL
eciECIElectronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mccMCCMCC for this transaction
options_3dsString3-D Secure flow option
cc_maskCC_MASKCard number mask
cc_tokenCC_TOKENFinancial Line card token generated for this card
cc_token_expirationStringToken expiration timestamp
customer_idStringCustomer identifier in merchant's system
customer_ipStringCustomer IP address
customer_fnameStringCustomer first name
customer_lnameStringCustomer last name
customer_emailStringCustomer email
customer_phoneStringCustomer phone
customer_countryStringCustomer country
result_urlURLCustomer will be redirected to this URL after payment.
created_atTIMESTAMPTimestamp when transaction was created
processing_timeTIMESTAMPTimestamp when transaction was updated last time
payloadStringField for custom data
bank_short_nameStringBank short name.

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "auth",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

In addition, the following data regarding the fingerprint of the payer's browser must be submitted in the request:

ParameterTypeDescription
browserColorDepthStringBrowser's color depth
browserScreenHeightStringBrowser's screen height
browserScreenWidthStringBrowser's screen width
browserJavaEnabledStringBrowser's java enabled
browserLanguageStringBrowser's language
browserTimeZoneStringBrowser's timezone
browserTimeZoneOffsetStringBrowser's timezone offset
browserAcceptHeaderStringBrowser's accept header
browserIpAddressStringBrowser's IP address
browserUserAgentStringBrowser's user agent

An example of a payer's browser fingerprint:

"browser_fingerprint": {
  "browserColorDepth":       "24",
  "browserScreenHeight":     "860",
  "browserScreenWidth":      "1600",
  "browserJavaEnabled":      "false",
  "browserLanguage":         "uk-UA",
  "browserTimeZone":         "Europe/Kiev",
  "browserTimeZoneOffset":   "-120",
  "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
  "browserIpAddress":        "127.0.0.1",
  "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
}

Hosted integration​

Hosted integration allows you to accept payments from customers from the Financial Line checkout.

Interaction format:

An image from the static

Hosted integration with two-step payments involves the following features (in addition to those described for one-step payment):

  • In a request to the Financial Line API, the method parameter must contain the auth value.

The rest of the parameters are similar to those provided for one-step payments.

Request example:

$ curl "https://api.finline.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY {API_KEY}:{API_SECRET}" \
    -H "X-API-KEY: {ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "{POS_ID}",
      "mode":             "hosted",
      "method":           "auth",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

A 303 HTTP response status to a successful request contains a Location header to which the customer should be redirected to proceed with payment.

Response example:

HTTP/2 303
# .. other headers
Location: "https://api.finline.io/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form"

Next steps​

The procedure for testing and going live is similar to that provided for one-step payment.

See also:​