API integration

Direct integration

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

Interaction format:

info

Note: the use of direct integration when collecting card data on the merchant side requires PCI DSS certification.

The use of direct integration with two-step payments involves the following peculiarities (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 split payments.

Depending on what is used in the request: 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 token: cc_token

info

In addition to supporting payments with tokens received after card payments, we also support tokens generated during the first payment via Apple Pay or Google Pay. These tokens should be passed in the cc_token parameter

For example:

"cc_token":"rcr:ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (token after an Apple Pay or Google Pay payment)
or
"cc_token": "ODJkZjBhNmY2OTMyND7sSjdD0S8TQzOXU3ZDFhYzI6cWJmWHFmMHlz M3hYaXJMWEZv" (token after a card payment).

Example request using card data:

$ 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",
      "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"
      }
    }'

Example request using token:

$ 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",
      "method":           "auth",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_token":         "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "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"
      }
    }'

Response parameters:

Parameter	Type	Required	Description
payment_id	UUID		Unique Financial Line payment identifier
order_id	String(≤256)	✅	Unique identifier of order
gateway_order_id	GW_ID		Unique order identifier in bank acquirer system.
billing_order_id	BILLING_ID		Unique Financial Line billing identifier
transaction_id	UUID		Financial Line transaction identifier
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	direct
method	METHOD	✅	Payment method (auth)
amount	Number	✅	Transaction amount
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String(≤2048)	✅	Payment description
status	STATUS		Transaction status
status_code	STATUS_CODE		Financial Line payment status code
status_description	STATUS_DESCRIPTION		Financial Line payment status code description
user_action_required	Boolean		Either customer action is required to proceed with payment
user_action_url	URL		If user_action_required is true then user should be redirected to this URL
eci	ECI		Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc	MCC		MCC for this transaction
options_3ds	String		3-D Secure flow option
cc_mask	CC_MASK		Card number mask
cc_token	CC_TOKEN		Financial Line card token generated for this card
cc_token_expiration	String		Token expiration timestamp
customer_id	String		Customer identifier in merchant's system
customer_ip	String	✅	Customer IP address
customer_fname	String	✅	Customer first name
customer_lname	String	✅	Customer last name
customer_email	String	✅	Customer email
customer_phone	String	✅	Customer phone
customer_country	String		Customer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
result_url	URL		Customer will be redirected to this URL after payment.
created_at	TIMESTAMP		Timestamp when transaction was created
processing_time	TIMESTAMP		Timestamp when transaction was updated last time
payload	String		Field for custom data
bank_short_name	String		Bank 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":                 "direct",
  "method":               "auth",
  "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:

Parameter	Type	Description
browserColorDepth	String	Browser's color depth
browserScreenHeight	String	Browser's screen height
browserScreenWidth	String	Browser's screen width
browserJavaEnabled	String	Browser's java enabled
browserLanguage	String	Browser's language
browserTimeZone	String	Browser's timezone
browserTimeZoneOffset	String	Browser's timezone offset
browserAcceptHeader	String	Browser's accept header
browserIpAddress	String	Browser's IP address
browserUserAgent	String	Browser'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 using the Financial Line payment page.

Interaction format:

The use of hosted integration with two-step payments involves the following peculiarities (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 for pre-authorization (auth) transaction are similar to those provided for one-step split 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",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
    }'

Next steps

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

See also:

• Payment capture
• Voiding pre-authorization
• Hosted checkout
• Adding payment methods