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 (`auth` or `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.
`cryptogram`	Json		Cryptogram parameters.
`customer_referrer`	URL		Page customer is redirected from.
`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" (токен після оплати карткою).

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

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

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

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 (`auth` or `purchase`)
`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 identifier in merchant's system
`customer_ip`	String	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
`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
`fee`	Object	Amount and currency of commission
`fixed_fee`	Object	Amount and currency of fixed commission (fee), which constitutes a portion of the total commission (fee)
`percent_fee`	Object	Amount and currency representing the interest commission (fee), which constitutes a portion of the total commission (fee)
`payload`	String	Field for custom data
`bank_short_name`	String	Bank 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":               "purchase",
  "amount":               1000,
  "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",
  "fee": {
                          "amount": 136,
                          "currency": "UAH"
  },
 "percent_fee": {
                          "amount": 126,
                          "currency": "UAH"
  },
  "fixed_fee": {
                          "amount": 10,
                          "currency": "UAH"
  },
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

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

Parameter	Type	Description
`processed_amount`	Number	The amount that was actually paid by the customer and processed by the payment system. It applies to payments where the final payment amount can be changed by the payer.
`processed_currency`	String(≤256)	Actual currency of payment with processed_amount. It applies to payments where the final payment amount can be changed by the payer.

Приклад відповіді з використанням змінюваних сум:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "refund",
  "amount":              1000,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "processed_amount":    980,
  "processed_currency":  "UAH",
  "fee":   {
                        "amount": 136,
                        "currency": "UAH"
  },
  "percent_fee": {
                        "amount": 126,
                        "currency": "UAH"
  },
  "fixed_fee": {
                        "amount": 10,
                        "currency": "UAH"
  }
}

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

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 (`auth` or `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
`order_timeout`	Integer		Payment lifespan. Value in seconds
`customer_tax_id`	String		Customer’s tax identification number

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

$ curl -i "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":           "purchase",
      "amount":           1,
      "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"
    }'

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

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

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

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

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

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

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

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

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

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

Регулярні платежі

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

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

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

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

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

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

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

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

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

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