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

API інтеграція

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

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

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

An image from the static

інформація

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

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

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

Окрім того, використання direct-інтеграції передбачає такі особливості:

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

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

ParameterTypeRequiredDescription
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEdirect
methodMETHODPayment method (lookup)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionStringPayment description
order_idStringUnique identified 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
productsArray[Product]Array of products to be paid
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)
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

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

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

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

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 (lookup)
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’s identifier in merchant's system
customer_ipStringCustomer’s IP address
customer_fnameStringCustomer’s first name
customer_lnameStringCustomer’s last name
customer_patronymStringCustomer’s patronym
customer_emailStringCustomer’s email
customer_phoneStringCustomer’s phone
customer_countryStringCustomer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthdayStringCustomer’s birthday (format: yyyy-MM-dd)
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.

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

{
"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": "lookup",
"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"
}

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

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

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

ParameterTypeRequiredDescription
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEhosted
methodMETHODPayment method (lookup)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionStringPayment description
order_idStringUnique identified 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
productsArray[Product]Array of products to be paid
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_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 merchant custom data. Max 4000 symbols.
validation_urlStringPreflight request will be sent to this URL
order_timeoutIntegerPayment lifespan. Value in seconds

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

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

Відповідь зі статусом 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. Коли наша команда Комплаєнсу активує робочий проєкт, замініть автентифікаційні дані тестового проєкту на дані робочого.

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