API integration

Direct-integration

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

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:

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. 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)

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:

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)

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:

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

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:

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:

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. 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)

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:

• Create an account in the merchant portal
• Use the authentication data of the test project.
• Configure webhooks.
• Use the test data to obtain different operation result codes.
• Handle received errors.

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:

• Recurring payment cancellation
• Refunds for recurring payments
• Obtaining information on subscriptions for recurring payments
• Hosted checkout