API інтеграція
Direct-інтеграція
Direct-інтеграція дозволить вам проводити перевірку платіжних карток, використовуючи власну платіжну сторінку.
Формат взаємодії:
Direct-інтеграція зі збиранням карткових даних на вашій стороні потребує проходження сертифікації PCI DSS.
Якщо платіжні дані збираються на вашій стороні, переконайтесь, що ви їх належним чином перевіряєте, а саме:
- Валідуйте строк дії картки.
- Проведіть перевірку номеру картки за алгоритмом Луна (Luhn algorithm).
- Перевірте, щоб введений CVV/CVC містив тільки цифри.
Окрім того, використання direct-інтеграції передбачає такі особливості:
- Платіжна сторінка повинна використовувати HTTPS-протокол.
- При direct-інтеграції ви можете робити запити з використанням повних платіжних даних або токенів.
- Дані кожного клієнта мають бути сталими та унікальними.
- Використовуйте HTTP-метод
POST
.
Параметри запиту:
Parameter | Type | Required | Description |
---|---|---|---|
pos_id | UUID | ✅ | Merchant's identifier (POS_ID ) |
mode | MODE | ✅ | direct |
method | METHOD | ✅ | Payment method (lookup ) |
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’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 |
Приклад запиту:
$ 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"
}'
Параметри відповіді:
Parameter | Type | Description |
---|---|---|
payment_id | UUID | Unique Financial Line payment identifier |
order_id | String(≤256) | Unique identifier of order |
gateway_order_id | GW_ID | Unique order identifier in bank acquirer system. |
billing_order_id | BILLING_ID | Unique Financial Line billing identifier |
transaction_id | UUID | Financial Line transaction identifier |
pos_id | UUID | Merchant's identifier (POS_ID ) |
mode | MODE | direct |
method | METHOD | Payment method (lookup ) |
amount | Number | Transaction amount |
currency | CURRENCY | Transaction currency (ISO_4217) |
description | String(≤2048) | Payment description |
status | STATUS | Transaction status |
status_code | STATUS_CODE | Financial Line payment status code |
status_description | STATUS_DESCRIPTION | Financial Line payment status code description |
user_action_required | Boolean | Either customer action is required to proceed with payment |
user_action_url | URL | If user_action_required is true then user should be redirected to this URL |
eci | ECI | Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure |
mcc | MCC | MCC for this transaction |
options_3ds | String | 3-D Secure flow option |
cc_mask | CC_MASK | Card number mask |
cc_token | CC_TOKEN | Financial Line card token generated for this card |
cc_token_expiration | String | Token expiration timestamp |
customer_id | String | Customer’s identifier in merchant's system |
customer_ip | String | Customer’s IP address |
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_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 ) |
result_url | URL | Customer will be redirected to this URL after payment. |
created_at | TIMESTAMP | Timestamp when transaction was created |
processing_time | TIMESTAMP | Timestamp when transaction was updated last time |
payload | String | Field 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"
}
Окрім того, в запиті обов’язково мають передаватися такі дані щодо фінгерпринту браузера платника:
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.
Формат взаємодії:
Параметри запиту:
Parameter | Type | Required | Description |
---|---|---|---|
pos_id | UUID | ✅ | Merchant's identifier (POS_ID ) |
mode | MODE | ✅ | hosted |
method | METHOD | ✅ | Payment method (lookup ) |
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’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_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 merchant custom data. Max 4000 symbols. | |
validation_url | String | Preflight request will be sent to this URL | |
order_timeout | Integer | Payment 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
Наступні кроки
Тестування платіжного процесу:
- Створіть обліковий запис у мерчант-порталі.
- Використовуйте автентифікаційні дані тестового проєкту.
- Налаштуйте вебхуки.
- Скористайтеся даними для тестування для отримання різних кодів результатів операцій.
- Опрацьовуйте отримані помилки.
Знайдіть більше деталей у контрольному списку інтеграції.
Вихід в онлайн:
- Створіть робочий проєкт у мерчант-порталі.
- При direct-інтеграції: пройдіть сертифікацію PCI DSS.
- Коли наша команда Комплаєнсу активує робочий проєкт, замініть автентифікаційні дані тестового проєкту на дані робочого.