Skip to main content

API integration

Direct-integration

Direct integration allows you to create subscriptions for recurring payments using your own payment page.

Interaction format:

Interaction format

To securely collect card data on your side through direct integration, it is essential to have PCI DSS certification.

To set up a subscription for recurring payments, it is necessary to meet the standard requirements for one-step payments, and additionally, provide specific parameters:

ParameterTypeRequiredDescription
interval_unitStringA type of time interval (day, week, month, quarter, year)
interval_countIntegerA 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_attemptsIntegerA number of retries after unsuccessful charge. The default value is 3. The max number is 7.
retry_interval_hoursIntegerA 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_dateDateThe date of the first scheduled charge (format: YYYY-MM-DD)
expiry_dateDateThe date of the last scheduled charge (format: YYYY-MM-DD)
timeTimeTime of each recurring charge in UTC. If not provided, the time of the recurring payment creation will be used. (format: HH:MM:SS)
notification_urlURLThe URL to receive notification for recurring payments. If not provided, the server_url value from the initial transaction will be used.
amountNumberThe 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.

Request example:

{
"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"
}
}

Alongside the standard parameters for one-step payments, the response also includes several additional parameters specific to recurring payments:

ParameterTypeDescription
recurring.idStringA unique identifier for all transactions within one recurring payment config
recurring.statusStringThe status of the specific recurring payment config (init/active/canceled)

Response example:

{
"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"
}

In addition, the following data regarding the fingerprint of the payer's browser must be submitted in the request:

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

An example of a payer's browser fingerprint:

 "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-integration

Hosted integration allows you to create subscriptions for recurring payments using the Financial Line checkout.

Interaction format:

Interaction format

To set up a subscription for recurring payments, it is necessary to meet the standard requirements for one-step payments, and additionally, provide specific parameters:

ParameterTypeRequiredDescription
interval_unitStringA type of time interval (day, week, month, quarter, year)
interval_countIntegerA 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_attemptsIntegerA number of retries after unsuccessful charge. The default value is 3. The max number is 7.
retry_interval_hoursIntegerA 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_dateDateThe date of the first scheduled charge (format: YYYY-MM-DD)
expiry_dateDateThe date of the last scheduled charge (format: YYYY-MM-DD)
timeTimeTime of each recurring charge in UTC. If not provided, the time of the recurring payment creation will be used. (format: HH:MM:SS)
notification_urlURLThe URL to receive notification for recurring payments. If not provided, the server_url value from the initial transaction will be used.
amountNumberThe 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.

Request example:

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

A 303 HTTP response status to a successful request contains a Location header to which the customer should be redirected to proceed with payment.

Response example:

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

Next steps

To test the subscription creation process:

Find more details in the integration checklist.

Going live:

  1. Create a live project in the merchant portal.
  2. With direct integration pass PCI DSS certification (if you intend to work with card data of the payers on your side).
  3. Upon activation of the live project by our Compliance Team, use its authentication data instead of the one of the test project.

See also: