API integration

Direct integration

Direct integration allows you to carry out cards verification using your own payment page.

Interaction format:

info

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

When collecting payment card data, ensure that you have the following validations in place:

• Card expiration date validation.
• Checking the card number according to the Luhn algorithm.
• The entered CVV/CVC contains only numbers.
  

In addition, the use of direct integration involves the following features:

• The payment page must use the HTTPS protocol.
• Customer details must be persistent and unique.
• Use the HTTP POST method.

Request parameters:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	direct
method	METHOD	✅	Payment method (lookup)
amount	Number	✅	Transaction amount
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identified of order
order_3ds_bypass	String	✅	3-D Secure flow option
cc_number	CC_NUMBER	✅	Card number
exp_month	Number	✅	Card expiration month field
exp_year	Number	✅	Card expiration year field
card_cvv	String	✅	Card CVV
products	Array[Product]		Array of products to be paid
customer_id	String		Customer identifier in merchant's system
customer_fname	String		Customer first name
customer_lname	String		Customer last name
customer_email	String		Customer email
customer_phone	String		Customer phone
customer_ip	String		Customer IP address
customer_country	String		Customer country
server_url	URL		Webhook notification will be sent to this URL
result_url	URL		Customer will be redirected to this URL after payment.
merchant_mcc	MCC		MCC for this transaction
payload	String		Field for merchant custom data. Max 4000 symbols.
validation_url	String		Preflight request will be sent to this URL

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",
      "method":           "lookup",
      "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"
    }'

Response parameters:

Parameter	Type	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 (lookup)
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
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.

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":               "lookup",
  "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"
}

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

With hosted integration, you can easily verify your customers' cards using the Financial Line checkout.

Interaction format:

Request parameters:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	hosted
method	METHOD	✅	Payment method (lookup)
amount	Number	✅	Transaction amount
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identified of order
order_3ds_bypass	String	✅	3-D Secure flow option
cc_number	CC_NUMBER	✅	Card number
exp_month	Number	✅	Card expiration month field
exp_year	Number	✅	Card expiration year field
card_cvv	String	✅	Card CVV
products	Array[Product]		Array of products to be paid
customer_id	String		Customer identifier in merchant's system
customer_fname	String		Customer first name
customer_lname	String		Customer last name
customer_email	String		Customer email
customer_phone	String		Customer phone
customer_ip	String		Customer IP address
customer_country	String		Customer country
server_url	URL		Webhook notification will be sent to this URL
result_url	URL		Customer will be redirected to this URL after payment.
merchant_mcc	MCC		MCC for this transaction
payload	String		Field for merchant custom data. Max 4000 symbols.
validation_url	String		Preflight request will be sent to this URL

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

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

To test the payment process:

• Create an account in the merchant portal.
• Use the authentication data of the test project.
• Configure webhooks.
• Use the test data to obtain different operation result codes.
• Handle received errors.

Find more details in the integration checklist.

Going live:

1. Reach out to Financial Line Support to initiate the creation of a live project.
2. For direct integration, it is essential to pass PCI DSS certification.
3. Upon activation of the live project by our Compliance Team, use its authentication data instead of the one of the test project.

See also:

• Hosted checkout
• Adding payment methods