API інтеграція

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

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

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

інформація

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

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

• Валідація строку дії картки.

• Перевіряйте номер картк за алгоритмом Луна (Luhn algorithm).

• Перевірте, щоб CVV/CVC містив тільки цифри
  
  

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

1. Платіжна сторінка повинна використовувати HTTPS-протокол.
2. Дані кожного клієнта мають бути сталими та унікальними.
3. Використовуйте 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 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
cc_token	String		Card token
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 (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
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
customer_tax_id	String		Customer’s tax identification number

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

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

інформація

Окрім платежів з токенами, що були отримані після оплати карткою, також підтримуються платежі за допомогою токенів, що були отримані під час першої оплати через платіжні методи 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)

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

$ curl "https://api.finline.io/api/v1/split/purchase" \
    -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":           "purchase",
      "amount":           100,
      "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",
      "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 ${API_KEY}:${API_SECRET}" \
    -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}"
          }
      ]
    }'

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

Parameter	Type	Required	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 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 (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
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
customer_tax_id	String		Customer’s tax identification number

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

{
  "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",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

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

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.

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

Для створення платежу за 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. 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 identified 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 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_lang	String		Checkout language. Supported values.
customer_country	String		Customer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
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
customer_tax_id	String		Customer’s tax identification number

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

$ curl -i "https://api.finline.io/api/v1/split/purchase" \
    -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":           "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)

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

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

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

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

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

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

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

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

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

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

• Проведення повернень
• Hosted-чекаут
• Додавання платіжних методів