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. |
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. |
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:
- Create a live project in the merchant portal.
- With direct integration pass PCI DSS certification (if you intend to work with card data of the payers on your side).
- Upon activation of the live project by our Compliance Team, use its authentication data instead of the one of the test project.