Перейти до основного вмісту

API інтеграція

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

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

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

An image from the static

інформація

Direct-інтеграція зі збиранням карткових даних на вашій стороні потребує проходження сертифікації PCI DSS.

Використання direct-інтеграції з двостадійними оплатами передбачає такі особливості (додатково до описаних щодо одностадійної оплати):

  • В запиті до API Financial Line параметр method повинен містити назву методу auth

В іншій частині запит на створення транзакції резервування повинен містити параметри аналогічні тим, що передбачені для одностадійних платежів.

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

  • Використання повних карткових даних: 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" (токен після оплати карткою).

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

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

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

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

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

ParameterTypeDescription
payment_idUUIDUnique Financial Line payment identifier
order_idString(≤256)Unique identifier of order
gateway_order_idGW_IDUnique order identifier in bank acquirer system.
billing_order_idBILLING_IDUnique Financial Line billing identifier
transaction_idUUIDFinancial Line transaction identifier
pos_idUUIDMerchant's identifier (POS_ID`)
modeMODEdirect
methodMETHODPayment method (auth)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionString(≤2048)Payment description
statusSTATUSTransaction status
status_codeSTATUS_CODEFinancial Line payment status code
status_descriptionSTATUS_DESCRIPTIONFinancial Line payment status code description
user_action_requiredBooleanEither customer action is required to proceed with payment
user_action_urlURLIf user_action_required is true then user should be redirected to this URL
eciECIElectronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mccMCCMCC for this transaction
options_3dsString3-D Secure flow option
cc_maskCC_MASKCard number mask
cc_tokenCC_TOKENFinancial Line card token generated for this card
cc_token_expirationStringToken expiration timestamp
customer_idStringCustomer identifier in merchant's system
customer_ipStringCustomer IP address
customer_fnameStringCustomer first name
customer_lnameStringCustomer last name
customer_emailStringCustomer email
customer_phoneStringCustomer phone
customer_countryStringCustomer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
result_urlURLCustomer will be redirected to this URL after payment.
created_atTIMESTAMPTimestamp when transaction was created
processing_timeTIMESTAMPTimestamp when transaction was updated last time
payloadStringField for custom data
bank_short_nameStringBank short name.

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

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

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

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

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

"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-інтеграції з двостадійними оплатами передбачає такі особливості (додатково до описаних щодо одностадійної оплати):

  • В запиті до API Financial Line параметр method повинен містити назву методу auth

В іншій частині запит на створення транзакції резервування повинен містити параметри аналогічні тим, що передбачені для одностадійних платежів.

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

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

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

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

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

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

Процедура тестування та виходу в онлайн є аналогічною тій, що передбачена для одностадійної оплати.

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