API інтеграція

Direct-інтеграція

Direct-інтеграція дозволить вам приймати спліт-платежі, використовуючи власну платіжну сторінку.

Формат взаємодії:

An image from the static

інформація

Використання direct-інтеграції потребує проходження сертифікації PCI DSS.

Якщо ви збираєте карткові дані самостійно, переконайтеся, що ви належним чином їх перевіряєте:

Валідація строку дії картки.
Перевіряйте номер картк за алгоритмом Луна (Luhn algorithm).
Перевірте, щоб CVV/CVC містив тільки цифри

Особливості використання direct-інтеграції:

Платіжна сторінка повинна використовувати HTTPS-протокол.
Дані кожного клієнта мають бути сталими та унікальними.
Використовуйте HTTP-метод POST.

Параметри запиту:

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	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)
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier 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
`cc_token`	String		Card token
`network_transaction_id`	String		Identifier 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_secure`	Object		External 3DS parameters.
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer’s identifier in merchant's system
`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_ip`	String	✅	Customer’s IP address
`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`)
`customer_referrer`	URL		Page customer is redirected from.
`customer_tax_id`	String		Customer’s tax identification number
`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
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
`cryptogram`	Json		Cryptogram parameters.
`customer_referrer`	URL		Page customer is redirected from.
`split`	Array[SplitPayment]	✅	Split payment properties

В залежності від того, що використовується у запиті: повні карткові дані чи токен, вам необхідно передавати такі параметри:

Використання повних карткових даних: cc_number, exp_month, exp_year, card_cvv.
Використання токенів cc_token.
Використання VTS / MDES токенів cc_number, exp_month, exp_year, cryptogram.

Окрім того, платіж з розшифрованим VTS / MDES токеном додатково має містити специфічні параметри в 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.

інформація

Окрім платежів з токенами, що були отримані після оплати карткою, також підтримуються платежі за допомогою токенів, що були отримані під час першої оплати через платіжні методи Apple Pay чи Google Pay. Ці токени будуть передаватися у параметрі cc_token.

Наприклад:

"cc_token":"rcr:ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (токен після оплати Apple Pay / Google Pay)
або
"cc_token":"ODJkZjBhNmY2OTMyND7sSjdD0S8TQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (токен після оплати карткою).

Окрім того, спліт-платіж додатково має містити специфічні параметри в масиві split:

Parameter	Type	Required	Description
`amount`	Number	✅	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_id`	UUID	✅	Unique Sub merchant identifier (to get the identifier, please contact support at support@finline.io)
`products`	Array[Product]		Array of products to be paid

інформація

У випадку, якщо потрібно провести платіж карткою, за якою автентифікація 3D Secure вже була виконана зовнішнім сервісом, необхідно у запиті використовувати параметр three_d_secure, що міститиме результат такої перевірки:

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

Приклад запиту з картковими даними:

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

Приклад запиту з токеном:

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

Приклад запиту з розшифрованим VTS / MDES токеном:

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

Параметри відповіді:

Parameter	Type	Description
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	Payment method (`purchase`)
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String	Payment description
`order_id`	String	Unique identifier 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’s identifier in merchant's system
`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_ip`	String	Customer’s IP address
`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`)
`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
`browser_fingerprint`	Json	Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
`split`	Array[SplitPayment]	Split payment properties
`receipt_url`	URL	URL link to the receipt for the corresponding transaction

Приклад відповіді:

{
  "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"
}

Окрім того, в запиті обов’язково мають передаватися такі дані щодо фінгерпринту браузера платника:

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

Приклад фінгерпринту браузера платника:

"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-інтеграція

Hosted-інтеграція дозволить вам приймати спліт-платежі від клієнтів з платіжної сторінки Financial Line.

Формат взаємодії:

An image from the static

Для створення платежу за hosted-інтеграцією використовуйте HTTP-метод POST.

Параметри запиту:

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`hosted`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`products`	Array[Product]		Array of products to be paid, empty array can be specified
`customer_id`	String		Customer’s identifier in merchant's system
`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_lang`	String		Checkout language. Supported values.
`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`)
`customer_tax_id`	String		Customer’s tax identification number
`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 custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL
`split`	Array[SplitPayment]	✅	Split payment properties

Приклад запиту:

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

Окрім того, спліт-платіж додатково має містити специфічні параметри в масиві split:

Parameter	Type	Required	Description
`amount`	Number	✅	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_id`	UUID	✅	Unique Sub merchant identifier (to get the identifier, please contact support at support@finline.io)
`products`	Array[Product]		Array of products to be paid

Відповідь зі статусом 303 HTTP на успішний запит містить заголовок location, в який клієнт повинен бути перенаправлений для продовження оплати.

Приклад відповіді:

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

Наступні кроки

Для тестування платіжного процесу:

Створіть обліковий запис у мерчант-порталі.
Використовуйте автентифікаційні дані тестового проєкту.
Налаштуйте вебхуки.
Скористайтеся даними для тестування для отримання різних кодів результатів операцій.
Опрацьовуйте отримані помилки.

Знайдіть більше деталей у контрольному списку інтеграції.

Вихід в онлайн:

Створіть робочий проєкт у мерчант-порталі.
При direct-інтеграції: пройдіть сертифікацію PCI DSS.
Коли наша команда Комплаєнсу активує робочий проєкт, замініть автентифікаційні дані тестового проєкту на дані робочого.

Direct-інтеграція​

Формат взаємодії:​

Hosted-інтеграція​

Формат взаємодії:​

Наступні кроки​

Вихід в онлайн:​

Дивіться також:​

Direct-інтеграція

Формат взаємодії:

Hosted-інтеграція

Формат взаємодії:

Наступні кроки

Вихід в онлайн:

Дивіться також: