API integration
Direct integration
Direct integration allows you to accept split payments using your own payment page.
Interaction format:
To securely collect card data on the merchant side through direct integration, it is essential to have PCI DSS certification in place.
When collecting payment card data, ensure that you have the following validations in place:
Card expiration date validation.
Checking the card number according to the (Luhn algorithm).
The entered CVV/CVC contains only numbers.
Features of using direct integration:
- The payment page must use the HTTPS protocol.
- Customer details must be persistent and unique.
- Use the HTTP
POST
method.
Request parameters:
Parameter | Type | Required | Description |
---|---|---|---|
pos_id | UUID | ✅ | Merchant's identifier (POS_ID ) |
mode | MODE | ✅ | direct |
method | METHOD | ✅ | Payment method (purchase ) |
amount | Number | ✅ | Transaction amount |
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 |
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 | |
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. | |
split | Array[SplitPayment] | ✅ | Split payment properties |
Depending on whether the request is full card data or a token, you need to pass the following parameters:
- Using full card data:
cc_number
,exp_month
,exp_year
,card_cvv
. - Using tokens:
cc_token
.
Moreover, the split payment must additionally contain specific parameters:
Parameter | Type | Required | Description |
---|---|---|---|
amount | Number | ✅ | Transaction amount |
sub_merchant_id | UUID | ✅ | Unique Sub merchant identifier (to get the identifier, please contact support at mailto:support@finline.io) |
Request example:
$ curl "https://api.finline.io/api/v1/split/purchase" \
-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": 100,
"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",
"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"
},
"split":[
{
"amount": 70,
"sub_merchant_id": "{SUB_MERCHANT_ID_1}"
},
{
"amount": 30,
"sub_merchant_id": "{SUB_MERCHANT_ID_2}"
}
]
}'
Response parameters:
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 (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 |
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 |
payload | String | Field for custom data |
bank_short_name | String | Bank short name. |
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": 100,
"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",
"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
With hosted integration, you can conveniently accept split payments from customers using the Financial Line checkout.
Interaction format:
To create a payment through the hosted integration, use the HTTP POST
method.
Request parameters:
Parameter | Type | Required | Description |
---|---|---|---|
pos_id | UUID | ✅ | Merchant's identifier (POS_ID ) |
mode | MODE | ✅ | hosted |
method | METHOD | ✅ | Payment method (purchase ) |
amount | Number | ✅ | Transaction amount |
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 | |
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 | |
split | Array[SplitPayment] | ✅ | Split payment properties |
In addition, the split payment must additionally contain specific parameters:
Parameter | Type | Required | Description |
---|---|---|---|
amount | Number | ✅ | Transaction amount |
sub_merchant_id | UUID | ✅ | Unique Sub merchant identifier (to get the identifier, please contact support at mailto:support@finline.io) |
Request example:
$ curl -i "https://api.finline.io/api/v1/split/purchase" \
-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": 100,
"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",
"split":[
{
"amount": 70,
"sub_merchant_id": "{SUB_MERCHANT_ID_1}"
},
{
"amount": 30,
"sub_merchant_id": "{SUB_MERCHANT_ID_2}"
}
]
}'
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 payment 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:
- Reach out to Financial Line Support to initiate the creation of a live project.
- For direct integration, it is essential to pass PCI DSS certification.
- Upon activation of the live project by our Compliance Team, use its authentication data instead of the one of the test project.