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

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
Using VTS / MDES tokens: cc_number, exp_month, exp_year, cryptogram.

Additionally, the decrypted VTS/ MDES payment must also include specific parameters in the cryptogram:

Parameter	Type	Required	Description
`type`	String	✅	Network token type: `vts` (Visa Token Service) or `mdes` (Mastercard Digital Enablement Service)
`cryptogram`	String	✅	Payment cryptogram in Base64 format. Issued by the tokenization network (Visa or Mastercard) and valid within a single transaction.
`eci`	String		Electronic Commerce Indicator. An indicator of the transaction’s authentication level, passed together with the cryptogram.

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).

info

If a payment is made with a card for which 3D Secure authentication has already been completed by an external service, the request must include the three_d_secure parameter containing the authentication result:

Parameter	Type	Required	Description
`cavv`	String	✅	Cardholder Authentication Verification Value. A cryptographic value derived by the cardholder’s bank after successful 3D Secure authentication.
`eci`	String	✅	Electronic Commerce Indicator. An indicator of the transaction’s authentication level, passed together with the cryptogram.
`ds_transaction_id`	String	✅	3DS directory service transaction ID. A unique identifier generated by the payment network's Directory Service to track a specific 3D Secure authentication attempt.
`status`	String	✅	3D Secure Transaction Status. The final result of the authentication process (for example, `Y` for successful or `A` for attempted).
`version`	String		3D Secure Message Version. The specific version of the 3D Secure protocol used for the authentication (for example, `2.1.0` or `2.2.0`).

Example request using card data:

$ curl "https://api.finline.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}" \
    -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":        "424242******4242",
      "exp_month":        2,
      "exp_year":         24,
      "cc_cvv":           "***",
      "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-HMAC-SHA256 ${API_KEY}:${SIGNATURE}" \
    -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"
      }
    }'

Example request using decrypted VTS / MDES token:

$ curl "https://api.finline.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id": "${POS_ID}",
      "mode": "direct",
      "method": "purchase",
      "amount": 1,
      "currency": "UAH",
      "description": "Order description",
      "order_id": "123",
      "cc_number": "4242424242424242",
      "exp_month": 2,
      "exp_year": 30,
      "cryptogram": {
        "type": "vts",
        "cryptogram": "AEIokIcx0ESqByEoIN1yAoABFA=",
        "eci": "05"
      },
      "customer_fname": "Olena",
      "customer_lname": "Shevchenko",
      "customer_id": "1234567890",
      "order_3ds_bypass": "never",
      "server_url": "https://callback.blackhole.com/callback"
    }'

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 (`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’s identifier in merchant's system
`customer_ip`	String	Customer’s IP address
`customer_fname`	String	Customer’s first name
`customer_lname`	String	Customer’s last name
`customer_patronym`	String	Customer’s patronym
`customer_email`	String	Customer’s email
`customer_phone`	String	Customer’s phone
`customer_country`	String	Customer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
`customer_birthday`	String	Customer’s birthday (format: `yyyy-MM-dd`)
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processed_at`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String	Field for custom data
`bank_short_name`	String	Bank short name.
`receipt_url`	URL	URL link to the receipt for the corresponding transaction

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",
  "processed_at":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name",
  "receipt_url":          "https://api.finline.io/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

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:

An image from the static

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-HMAC-SHA256 ${API_KEY}:${SIGNATURE}" \
    -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.

Direct integration​

Hosted integration​

Next steps​

See also:​

Direct integration

Hosted integration

Next steps

See also: