API інтеграція

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

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

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

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

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

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

Parameter	Type	Required	Description
`interval_unit`	String	✅	A type of time interval (day, week, month, quarter, year)
`interval_count`	Integer	✅	A number of time intervals between charges. For example, if the charge should take place once per 3 weeks, the following parameters should be passed: `interval_unit: week` and `interval_count: 3` The max number is 30.
`retry_attempts`	Integer	✅	A number of retries after unsuccessful charge. The default value is 3. The max number is 7.
`retry_interval_hours`	Integer	✅	A number of hours between retries. The default values are: IF `interval_unit = day` `retry_interval_hours = 2` ELSE `retry_interval_hours = 24` The max values are: IF `interval_unit = day` `retry_interval_hours = 23` ELSE `retry_interval_hours = 72`
`start_date`	Date		The date of the first scheduled charge (format: YYYY-MM-DD)
`expiry_date`	Date		The date of the last scheduled charge (format: YYYY-MM-DD)
`time`	Time		Time of each recurring charge in UTC. If not provided, the time of the recurring payment creation will be used. (format: HH:MM:SS)
`notification_url`	URL		The URL to receive notification for recurring payments. If not provided, the `server_url` value from the initial transaction will be used.
`amount`	Number		The recurring payment amount if it is different from the one of the initial transaction. If not specified, it will default to the initial transaction amount.

Приклад запиту на створення підписки на регулярні платежі:

{
  "pos_id":"'$POS_ID'",
  "mode":"direct",
  "method":"purchase",
  "amount":10,
  "currency":"USD",
  "cc_number":"4111111111111111",
  "exp_month":4,
  "exp_year":42,
  "card_cvv":"123",
  "payway":"pgi_stub",
  "order_id":"'$ORDER_ID'",
  "description":"Testing of recurring",
  "customer_lang":"en",
  "customer_fname":"name",
  "customer_email":"test@test.com",
  "server_url":"https://webhook.site/ab720654-db8a-4d51-9750-8446c295dbd0",
  "order_3ds_bypass":"always",
  "init_recurring":{
    "interval_unit":"day",
    "interval_count":1,
    "retry_attempts":3,
    "retry_interval_hours":1,
    "start_date":"2022-12-13",
    "expiry_date":"2022-12-20",
    "time":"18:42:00",
    "notification_url":"https://webhook.site/ab720654-db8a-4d51-9750-8446c295dbd0"
  }
}

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

Parameter	Type	Description
`recurring.id`	String	A unique identifier for all transactions within one recurring payment config
`recurring.status`	String	The status of the specific recurring payment config (init/active/canceled)

Приклад відповіді на запит на створення підписки на регулярні платежі:

{
  "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":               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",
  "recurring": {
    "id": "r7dAMIRmS~3nCiHVFpSC8",
    "status": "init"
  },
  "result_url":           "https://example.com/result",
  "created_at":           "2023-09-14T14:08:13.509",
  "processed_at":         "2023-09-14T14:08:16.112",
  "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.

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

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

Parameter	Type	Required	Description
`interval_unit`	String	✅	A type of time interval (day, week, month, quarter, year)
`interval_count`	Integer	✅	A number of time intervals between charges. For example, if the charge should take place once per 3 weeks, the following parameters should be passed: `interval_unit: week` and `interval_count: 3` The max number is 30.
`retry_attempts`	Integer	✅	A number of retries after unsuccessful charge. The default value is 3. The max number is 7.
`retry_interval_hours`	Integer	✅	A number of hours between retries. The default values are: IF `interval_unit = day` `retry_interval_hours = 2` ELSE `retry_interval_hours = 24` The max values are: IF `interval_unit = day` `retry_interval_hours = 23` ELSE `retry_interval_hours = 72`
`start_date`	Date		The date of the first scheduled charge (format: YYYY-MM-DD)
`expiry_date`	Date		The date of the last scheduled charge (format: YYYY-MM-DD)
`time`	Time		Time of each recurring charge in UTC. If not provided, the time of the recurring payment creation will be used. (format: HH:MM:SS)
`notification_url`	URL		The URL to receive notification for recurring payments. If not provided, the `server_url` value from the initial transaction will be used.
`amount`	Number		The recurring payment amount if it is different from the one of the initial transaction. If not specified, it will default to the initial transaction amount.

Приклад запиту на створення підписки на регулярні платежі:

$ 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}",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      //-----validation fields------
      "mode":             "hosted",
      "method":           "purchase",
      "order_3ds_bypass": "always",
      "init_recurring":   {
            "interval_unit": "monthly",
            "interval_count": 1,
            "retry_attempts": 3,
            "retry_interval_hours": 24,
            "start_date": "2022-10-03"
            "expiry_date": "2022-10-10",
            "time": "10:00:00",
            "notification_url": "https://webhook.site/ab720654-db8a-4d51-9750-8446c295dbd0"
            "amount": 20
      }
    }'

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

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

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

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

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

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

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

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

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

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

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