Skip to main content

API integration

Direct integration​

Direct integration allows you to accept split payments using your own payment page. At the same time, the integration allows making payments using payment cards and alternative payment methods.

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.

If using direct integration, if payment data is collected on your end, make sure that it is properly validated on your page, including:

  • Card expiration date validation.

  • Checking the card number according to the (Luhn algorithm).

  • The entered CVV/CVC contains only numbers.

Features of using direct integration:

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

Request parameters:

ParameterTypeRequiredDescription
pos_idUUID✅Merchant's identifier (POS_ID)
modeMODE✅direct
methodMETHOD✅Payment method (purchase)
amountNumber✅Transaction amount
currencyCURRENCY✅Transaction currency (ISO_4217)
descriptionString✅Payment description
order_idString✅Unique identifier of order
order_3ds_bypassString✅3-D Secure flow option
cc_numberCC_NUMBERCard number
exp_monthNumberCard expiration month field
exp_yearNumberCard expiration year field
card_cvvStringCard CVV
cc_tokenStringCard token
network_transaction_idStringIdentifier used by financial networks (Visa, Mastercard, AmEx, etc.) to identify a transaction. This value is present if it is returned by the financial network in the authorization response.
three_d_secureObjectExternal 3DS parameters.
productsArray[Product]Array of products to be paid
customer_idStringCustomer’s identifier in merchant's system
customer_fnameString✅Customer’s first name
customer_lnameString✅Customer’s last name
customer_patronymStringCustomer’s patronym
customer_emailString✅Customer’s email
customer_phoneString✅Customer’s phone
customer_ipString✅Customer’s IP address
customer_countryStringCustomer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthdayStringCustomer's birthday (format: yyyy-MM-dd)
customer_referrerURLPage customer is redirected from.
customer_tax_idStringCustomer’s tax identification number
server_urlURLWebhook notification will be sent to this URL
result_urlURLCustomer will be redirected to this URL after payment.
merchant_mccMCCMCC for this transaction
payloadStringField for merchant custom data. Max 4000 symbols.
validation_urlStringPreflight request will be sent to this URL
browser_fingerprintJsonBrowser fingerprint. These parameters could be used in 3DS 2.0 verification.
cryptogramJsonCryptogram parameters.
customer_referrerURLPage customer is redirected from.
splitArray[SplitPayment]✅Split payment properties

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.
  • 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:

ParameterTypeRequiredDescription
typeString✅Network token type: vts (Visa Token Service) or mdes (Mastercard Digital Enablement Service)
cryptogramString✅Payment cryptogram in Base64 format. Issued by the tokenization network (Visa or Mastercard) and valid within a single transaction.
eciStringElectronic 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).

Additionally, the split payment must also include specific parameters in the split array:

ParameterTypeRequiredDescription
amountNumber✅Transaction amount. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
sub_merchant_idUUID✅Unique Sub merchant identifier (to get the identifier, please contact support at support@finline.io)
productsArray[Product]Array of products to be paid
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:

ParameterTypeRequiredDescription
cavvString✅Cardholder Authentication Verification Value. A cryptographic value derived by the cardholder’s bank after successful 3D Secure authentication.
eciString✅Electronic Commerce Indicator. An indicator of the transaction’s authentication level, passed together with the cryptogram.
ds_transaction_idString✅3DS directory service transaction ID. A unique identifier generated by the payment network's Directory Service to track a specific 3D Secure authentication attempt.
statusString✅3D Secure Transaction Status. The final result of the authentication process (for example, Y for successful or A for attempted).
versionString3D 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/split/purchase" \
    -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":           100,
      "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",
      "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"
      },
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]
    }'

Example request using token:

$ curl "https://api.finline.io/api/v1/split/purchase" \
    -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":           100,
      "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",
      "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"
      },
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]
    }'

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:

ParameterTypeDescription
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEdirect
methodMETHODPayment method (purchase)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionStringPayment description
order_idStringUnique identifier of order
order_3ds_bypassString3-D Secure flow option
cc_numberCC_NUMBERCard number
exp_monthNumberCard expiration month field
exp_yearNumberCard expiration year field
card_cvvStringCard CVV
customer_idStringCustomer’s identifier in merchant's system
customer_fnameStringCustomer’s first name
customer_lnameStringCustomer’s last name
customer_patronymStringCustomer’s patronym
customer_emailStringCustomer’s email
customer_phoneStringCustomer’s phone
customer_ipStringCustomer’s IP address
customer_countryStringCustomer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthdayStringCustomer’s birthday (format: yyyy-MM-dd)
server_urlURLWebhook notification will be sent to this URL
result_urlURLCustomer will be redirected to this URL after payment.
merchant_mccMCCMCC for this transaction
payloadStringField for merchant custom data. Max 4000 symbols.
validation_urlStringPreflight request will be sent to this URL
browser_fingerprintJsonBrowser fingerprint. These parameters could be used in 3DS 2.0 verification.
splitArray[SplitPayment]Split payment properties

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":               "purchase",
  "amount":               100,
  "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:

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​

The Hosted integration will allow you to accept split payments from customers from the Financial Line payment page. This payment method provides an ability to use payment cards, Apple Pay and Google Pay™ digital wallets, as well as local payment methods.

Interaction format:​

An image from the static

To create a payment through the hosted integration, use the HTTP POST method.

Request parameters:

ParameterTypeRequiredDescription
pos_idUUID✅Merchant's identifier (POS_ID)
modeMODE✅hosted
methodMETHOD✅Payment method (purchase)
amountNumber✅Transaction amount
currencyCURRENCY✅Transaction currency (ISO_4217)
descriptionString✅Payment description
order_idString✅Unique identifier of order
order_3ds_bypassString✅3-D Secure flow option
customer_idStringCustomer’s identifier in merchant's system
customer_fnameStringCustomer’s first name
customer_lnameStringCustomer’s last name
customer_patronymString✅Customer’s patronym
customer_emailString✅Customer’s email
customer_phoneString✅Customer’s phone
customer_langStringCheckout language. Supported values.
customer_countryStringCustomer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthdayStringCustomer's birthday (format: yyyy-MM-dd)
customer_tax_idStringCustomer’s tax identification number
server_urlURLWebhook notification will be sent to this URL
result_urlURLCustomer will be redirected to this URL after payment.
merchant_mccMCCMCC for this transaction
payloadStringField for custom data. Max 4000 symbols.
validation_urlURLPreflight request will be sent to this URL
splitArray[SplitPayment]✅Split payment properties

Additionally, the split payment must also include specific parameters in the split array:

ParameterTypeRequiredDescription
amountNumber✅Transaction amount. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
sub_merchant_idUUID✅Unique Sub merchant identifier (to get the identifier, please contact support at support@finline.io)
productsArray[Product]Array of products to be paid

Request example:

$ curl -i "https://api.finline.io/api/v1/split/purchase" \
    -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":           "purchase",
      "amount":           100,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]
    }'

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:

Find more details in the integration checklist.

After completing the test to go live, you need:​

  1. Create a live project in the merchant portal.
  2. With direct integration: pass PCI DSS certification (if you intend to work with card data of payers on your side).
  3. After receiving information from our Compliance team about the completion of the settings for the project, make changes to the authentication data using the data of the live project.
  4. You are ready to receive payments from your customers.

See also:​